Add agent guide and skills documentation

.cursor/rules/README.md

@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
+
+This folder only points contributors to **AGENTS.md** so editor-specific config does not duplicate the canonical docs.

.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: Release datasync asset store filesystem
+on:
+  release:
+    types: [created]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22.x"
+      - name: Installing dependencies
+        run: npm install
+      - name: Build
+        run: npm run build-ts
+      - name: Publishing datasync asset store filesystem
+        id: publish-to-npm
+        uses: JS-DevTools/npm-publish@v2.2.1
+        with:
+          token: ${{ secrets.NPM_TOKEN }}
+      - name: github-release
+        id: github-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run:  gh release create v${{ steps.publish-to-npm.outputs.version }} --title "Release ${{ steps.publish-to-npm.outputs.version }}" --generate-notes
+

AGENTS.md

@@ -0,0 +1,47 @@
+# DataSync Asset Store Filesystem – Agent guide
+
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
+
+## What this repo is
+
+| Field | Detail |
+| --- | --- |
+| **Name:** | [contentstack/datasync-asset-store-filesystem](https://github.com/contentstack/datasync-asset-store-filesystem) (`@contentstack/datasync-asset-store-filesystem` on npm) |
+| **Purpose:** | Filesystem-backed asset store for Contentstack DataSync: downloads and stores asset files locally for use with DataSync Manager and related modules. |
+| **Out of scope (if any):** | Not a standalone HTTP server or full DataSync stack—pairs with DataSync Manager, webhook listener, and a content store. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| Language | TypeScript → CommonJS in `dist/` (`tsconfig.json`; target ES6, `src/` only in compile). Node **20+** per README (`.travis.yml` lists older Node for legacy CI). |
+| Build | `npm run build-ts` (`tsc` → `dist/`), `npm run compile` / `prepare`. Hand-written typings under `typings/`. |
+| Tests | Jest (`jest.config.js`), tests under `test/` as `*.js` (`testRegex`). |
+| Lint / coverage | TSLint (`tslint.json`, `npm run tslint`). Jest `--coverage` outputs to `coverage/`. |
+| Runtime deps | `debug`, `lodash`, `rimraf`, `undici` (HTTP for downloads). |
+
+## Commands (quick reference)
+
+| Command type | Command |
+| --- | --- |
+| Build | `npm run build-ts` |
+| Test | `npm test` (runs `pretest`: `build-ts` then cleans `_contents` / `coverage`) |
+| Lint | `npm run tslint` |
+
+CI: `.travis.yml` runs `npm run build-ts` and `npm run test`. GitHub Actions: `.github/workflows/` (e.g. CodeQL, policy/SCA scans, issues automation). Pre-commit (optional): `.husky/pre-commit` expects Talisman and Snyk when enabled.
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Dev workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | npm scripts, CI, `example/`, optional git hooks. |
+| TypeScript style | [`skills/typescript-style/SKILL.md`](skills/typescript-style/SKILL.md) | `tsconfig.json`, `typings/`, TSLint. |
+| DataSync asset store API | [`skills/datasync-asset-store/SKILL.md`](skills/datasync-asset-store/SKILL.md) | Public API, `FSAssetStore`, config, DataSync integration. |
+| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | Jest layout, coverage, test vs source paths. |
+| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist for this package. |
+
+An index with “when to use” hints is in [`skills/README.md`](skills/README.md).
+
+## Using Cursor (optional)
+
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentstack/datasync-asset-store-filesystem",
-  "version": "2.3.5",
+  "version": "2.3.4",
   "description": "Fillesystem asset store for DataSync libraries. Stores Contentstack asset-files in filesystem",
   "main": "./dist",
   "types": "./typings",

skills/README.md

@@ -0,0 +1,15 @@
+# Skills – DataSync Asset Store Filesystem
+
+Source of truth for detailed guidance. Read [`AGENTS.md`](../AGENTS.md) first, then open the skill that matches your task.
+
+## When to use which skill
+
+| Skill folder | Use when |
+| --- | --- |
+| [`dev-workflow`](dev-workflow/SKILL.md) | npm scripts, CI, `example/`, hooks. |
+| [`typescript-style`](typescript-style/SKILL.md) | `tsconfig.json`, `typings/`, TSLint, TypeScript/source layout. |
+| [`datasync-asset-store`](datasync-asset-store/SKILL.md) | Public API, configuration, DataSync Manager integration, asset download/unpublish behavior. |
+| [`testing`](testing/SKILL.md) | Writing or running Jest tests, coverage, `test/` layout. |
+| [`code-review`](code-review/SKILL.md) | Reviewing or preparing PRs for this library. |
+
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

skills/code-review/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: code-review
+description: PR review checklist for datasync-asset-store-filesystem — use when opening or reviewing pull requests.
+---
+
+# Code review – DataSync Asset Store Filesystem
+
+## When to use
+
+- Opening a PR that touches `src/`, tests, or published artifacts
+- Reviewing changes for a library release
+
+## Instructions
+
+- **Build and tests:** Branch should pass `npm run build-ts` and `npm test` locally.
+- **Lint:** Run `npm run tslint` for TypeScript changes in `src/`.
+- **API and docs:** If public behavior or defaults change, update root `README.md` and verify [`datasync-asset-store`](../datasync-asset-store/SKILL.md) assumptions still hold.
+- **Versioning:** Bump `package.json` version when releasing; follow org conventions for tags and changelog if applicable.
+- **Security:** Avoid logging secrets; path handling should remain safe (see existing sanitization in `src/utils.ts` and related code). Large dependency or HTTP behavior changes deserve extra scrutiny.
+- **Scope:** Keep changes focused on the asset-store concern—avoid unrelated refactors in the same PR unless required for the fix.

skills/datasync-asset-store/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: datasync-asset-store
+description: Public API and DataSync integration for the filesystem asset store — use for start, FSAssetStore, config, and asset paths.
+---
+
+# DataSync asset store API – DataSync Asset Store Filesystem
+
+## When to use
+
+- Implementing or changing how assets are downloaded, stored, or removed on disk
+- Wiring this package into DataSync Manager (`setAssetStore`)
+- Debugging URL parsing, `baseDir`, or path patterns
+
+## Instructions
+
+- **Entry:** Consumers typically `require('@contentstack/datasync-asset-store-filesystem')` and pass the module to DataSync Manager; the package `main` is `./dist` (compiled from `src/index.ts`).
+- **Lifecycle:** Call `start(config)` to get a `Promise` that resolves to an `FSAssetStore` instance. `setConfig` / `getConfig` hold merged config; `assetStoreInstance` is exported for the active instance after `start`.
+- **Class:** `FSAssetStore` (`src/filesystem.ts`) implements download/unpublish flows using `undici` for HTTP, `fs` for writes, and helpers from `src/index.ts` for paths.
+- **Path helpers:** `getAssetLocation` and `getFileLocation` build directory/file paths from asset URLs and `assetStore` config (`pattern`, `patternWithBranch`, optional `assetFolderPrefixKey`). Contentstack asset hostnames are matched via regex in `src/index.ts`.
+- **Defaults:** `defaultConfig` in `src/config.ts` — e.g. `assetStore.baseDir: './_contents'`, `pattern` and `patternWithBranch` for folder layout. Merge with app config as in the README example.
+- **Cross-module config:** README documents `content-store-filesystem.baseDir` alongside this module; keep docs aligned when changing default paths.
+- **Errors:** User-facing strings and errors are centralized in `src/messages.ts` where applicable.

skills/dev-workflow/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: dev-workflow
+description: npm scripts, CI, and repo workflow for datasync-asset-store-filesystem — use for build/test commands, example app, and hooks.
+---
+
+# Dev workflow – DataSync Asset Store Filesystem
+
+## When to use
+
+- Running or changing build or test commands
+- Working in `example/` or understanding CI / automation
+- Optional git hooks (Talisman, Snyk)
+
+## Instructions
+
+- **Install:** `npm install`. Target Node **20+** for local dev (see root `README.md`).
+- **Build:** `npm run build-ts` runs `clean` then `tsc`; output is `dist/`. `npm run compile` is `tsc` only; `prepare` runs compile for pack/install.
+- **Watch:** `npm run watch-ts` for incremental compile during development.
+- **Example app:** `example/` demonstrates wiring with mock config (not the full DataSync stack).
+- **Travis:** `.travis.yml` runs `npm run build-ts` then `npm run test` on its Node matrix (may differ from README’s recommended Node version).
+- **GitHub Actions:** `.github/workflows/` — security/scanning, release, and automation; see each workflow for triggers.
+- **Husky (optional):** `.husky/pre-commit` runs Talisman and Snyk if installed; `SKIP_HOOK=1` bypasses. Not everyone has these CLI tools—coordinate with the team before relying on the hook locally.
+
+TypeScript compiler options, `typings/`, and TSLint: **`skills/typescript-style/SKILL.md`**.

skills/testing/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: testing
+description: Jest tests and coverage for datasync-asset-store-filesystem — use for test layout, pretest build, and coverage output.
+---
+
+# Testing – DataSync Asset Store Filesystem
+
+## When to use
+
+- Adding or changing tests under `test/`
+- Interpreting coverage reports or Jest configuration
+- Debugging `pretest` / build ordering before tests run
+
+## Instructions
+
+- **Runner:** `npm test` runs Jest with `--coverage`. `pretest` runs `npm run build-ts` and removes `_contents` and `coverage` so tests run against a fresh build and clean asset dirs where relevant.
+- **Test files:** `jest.config.js` sets `testRegex: "./test/.*.js$"` and `testEnvironment: "node"`. Tests are JavaScript under `test/`, not co-located `*.spec.ts` in `src/`.
+- **Coverage:** Output directory `coverage/`; reporters include `json` and `html`. `coveragePathIgnorePatterns` excludes `node_modules`, `test-utils`, `test_content`, and parts of `dist/` — adjust in `jest.config.js` if you add new paths that should be ignored or included.
+- **Integration style:** `example/` and `test/` may use mocks; avoid committing real API keys or secrets (align with Talisman/Snyk expectations if hooks are used).

skills/typescript-style/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: typescript-style
+description: TypeScript compiler settings, hand-written typings, and TSLint for this repo — use when changing tsconfig, typings, or lint rules.
+---
+
+# TypeScript style – DataSync Asset Store Filesystem
+
+## When to use
+
+- Editing `tsconfig.json`, `tslint.json`, or files under `typings/`
+- Adding or changing `.ts` under `src/` and need to align with existing strictness and lint
+- Debugging compile errors vs published types
+
+## Instructions
+
+- **Compiler:** `tsconfig.json` compiles only `src/**/*` to `dist/` (`module` CommonJS, `target` ES6, `moduleResolution` node, `alwaysStrict`, `noUnusedLocals` / `noUnusedParameters`, `noImplicitReturns`, etc.). Do not widen options without a deliberate reason—match existing patterns.
+- **Declarations:** Public types ship from **`typings/`** (`package.json` has `"types": "./typings"`). Keep `.d.ts` in sync with `src/` exports; the build does not emit declarations from `tsc` (declaration options are commented out in tsconfig).
+- **Lint:** `npm run tslint` uses `tslint.json` extending `tslint:recommended` on `src/**/*.ts`. Notable rules include max line length 120, 2-space indent, `no-default-export`, interface names prefixed with `I` where the rule applies—follow fixes consistent with nearby files.
+- **Dependencies:** `@types/node` and `@types/jest` versions in `package.json` are pinned for compatibility; bump types together with TS upgrades when needed.