From 7586233277a623cd46840a7bc1d3d3b42bb0ece2 Mon Sep 17 00:00:00 2001 From: harshitha-cstk Date: Fri, 10 Apr 2026 12:23:31 +0530 Subject: [PATCH] Add agent guide and skills documentation --- .cursor/rules/README.md | 5 +++ .github/workflows/release.yml | 27 ++++++++++++++++ AGENTS.md | 47 ++++++++++++++++++++++++++++ package-lock.json | 42 ++++++++++++------------- package.json | 2 +- skills/README.md | 15 +++++++++ skills/code-review/SKILL.md | 20 ++++++++++++ skills/datasync-asset-store/SKILL.md | 22 +++++++++++++ skills/dev-workflow/SKILL.md | 24 ++++++++++++++ skills/testing/SKILL.md | 19 +++++++++++ skills/typescript-style/SKILL.md | 19 +++++++++++ 11 files changed, 220 insertions(+), 22 deletions(-) create mode 100644 .cursor/rules/README.md create mode 100644 .github/workflows/release.yml create mode 100644 AGENTS.md create mode 100644 skills/README.md create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/datasync-asset-store/SKILL.md create mode 100644 skills/dev-workflow/SKILL.md create mode 100644 skills/testing/SKILL.md create mode 100644 skills/typescript-style/SKILL.md diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..d107daa --- /dev/null +++ b/.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. diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..9e084ba --- /dev/null +++ b/.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 + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d7ba57d --- /dev/null +++ b/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. diff --git a/package-lock.json b/package-lock.json index de96e15..dcbe87e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@contentstack/datasync-asset-store-filesystem", - "version": "2.3.5", + "version": "2.3.4", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@contentstack/datasync-asset-store-filesystem", - "version": "2.3.5", + "version": "2.3.4", "license": "MIT", "dependencies": { "debug": "^4.4.3", @@ -1232,9 +1232,9 @@ "license": "MIT" }, "node_modules/baseline-browser-mapping": { - "version": "2.10.13", - "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.13.tgz", - "integrity": "sha512-BL2sTuHOdy0YT1lYieUxTw/QMtPBC3pmlJC6xk8BBYVv6vcw3SGdKemQ+Xsx9ik2F/lYDO9tqsFQH1r9PFuHKw==", + "version": "2.10.17", + "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.17.tgz", + "integrity": "sha512-HdrkN8eVG2CXxeifv/VdJ4A4RSra1DTW8dc/hdxzhGHN8QePs6gKaWM9pHPcpCoxYZJuOZ8drHmbdpLHjCYjLA==", "dev": true, "license": "Apache-2.0", "bin": { @@ -1381,9 +1381,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001784", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001784.tgz", - "integrity": "sha512-WU346nBTklUV9YfUl60fqRbU5ZqyXlqvo1SgigE1OAXK5bFL8LL9q1K7aap3N739l4BvNqnkm3YrGHiY9sfUQw==", + "version": "1.0.30001787", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001787.tgz", + "integrity": "sha512-mNcrMN9KeI68u7muanUpEejSLghOKlVhRqS/Za2IeyGllJ9I9otGpR9g3nsw7n4W378TE/LyIteA0+/FOZm4Kg==", "dev": true, "funding": [ { @@ -1697,9 +1697,9 @@ } }, "node_modules/electron-to-chromium": { - "version": "1.5.331", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.331.tgz", - "integrity": "sha512-IbxXrsTlD3hRodkLnbxAPP4OuJYdWCeM3IOdT+CpcMoIwIoDfCmRpEtSPfwBXxVkg9xmBeY7Lz2Eo2TDn/HC3Q==", + "version": "1.5.334", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.334.tgz", + "integrity": "sha512-mgjZAz7Jyx1SRCwEpy9wefDS7GvNPazLthHg8eQMJ76wBdGQQDW33TCrUTvQ4wzpmOrv2zrFoD3oNufMdyMpog==", "dev": true, "license": "ISC" }, @@ -3484,9 +3484,9 @@ } }, "node_modules/path-scurry/node_modules/lru-cache": { - "version": "11.2.7", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.7.tgz", - "integrity": "sha512-aY/R+aEsRelme17KGQa/1ZSIpLpNYYrhcrepKTZgE+W3WM16YMCaPwOHLHsmopZHELU0Ojin1lPVxKR0MihncA==", + "version": "11.3.3", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.3.3.tgz", + "integrity": "sha512-JvNw9Y81y33E+BEYPr0U7omo+U9AySnsMsEiXgwT6yqd31VQWTLNQqmT4ou5eqPFUrTfIDFta2wKhB1hyohtAQ==", "license": "BlueOak-1.0.0", "engines": { "node": "20 || >=22" @@ -3602,9 +3602,9 @@ "license": "MIT" }, "node_modules/qs": { - "version": "6.15.0", - "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.0.tgz", - "integrity": "sha512-mAZTtNCeetKMH+pSjrb76NAM8V9a05I9aBZOHztWy/UqcJdQYNsf59vrRKWnojAT9Y+GbIvoTBC++CPHqpDBhQ==", + "version": "6.15.1", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.1.tgz", + "integrity": "sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==", "dev": true, "license": "BSD-3-Clause", "dependencies": { @@ -3858,14 +3858,14 @@ } }, "node_modules/side-channel-list": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.0.tgz", - "integrity": "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==", + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz", + "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==", "dev": true, "license": "MIT", "dependencies": { "es-errors": "^1.3.0", - "object-inspect": "^1.13.3" + "object-inspect": "^1.13.4" }, "engines": { "node": ">= 0.4" diff --git a/package.json b/package.json index 67b125f..c1df63a 100644 --- a/package.json +++ b/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", diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..fd30e39 --- /dev/null +++ b/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`). diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..b4767c9 --- /dev/null +++ b/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. diff --git a/skills/datasync-asset-store/SKILL.md b/skills/datasync-asset-store/SKILL.md new file mode 100644 index 0000000..d35e787 --- /dev/null +++ b/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. diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md new file mode 100644 index 0000000..0ef705a --- /dev/null +++ b/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`**. diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md new file mode 100644 index 0000000..c967807 --- /dev/null +++ b/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). diff --git a/skills/typescript-style/SKILL.md b/skills/typescript-style/SKILL.md new file mode 100644 index 0000000..a5cc6ff --- /dev/null +++ b/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.