From e064d35b2f6a82134d33701d42fd5e78ad7811e8 Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Wed, 25 Feb 2026 12:13:54 -0500 Subject: [PATCH 1/2] chore: add repository-specific copilot instructions --- .github/copilot-instructions.md | 81 +++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..758bf06 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,81 @@ +# capiscio-node - GitHub Copilot Instructions + +## ABSOLUTE RULES - NO EXCEPTIONS + +### 1. ALL WORK VIA PULL REQUESTS +- **NEVER commit directly to `main`.** All changes MUST go through PRs. + +### 2. LOCAL CI VALIDATION BEFORE PUSH +- Run: `pnpm test` and `pnpm build` + +### 3. NO WATCH/BLOCKING COMMANDS +- **NEVER run blocking commands** without timeout + +--- + +## CRITICAL: Read First + +**Before starting work, read the workspace context files:** +1. `../../.context/CURRENT_SPRINT.md` - Sprint goals and priorities +2. `../../.context/ACTIVE_TASKS.md` - Active tasks + +--- + +## Repository Purpose + +**capiscio-node** is the Node.js/npm CLI wrapper for capiscio-core. It auto-downloads +the platform-specific Go binary and passes all commands through transparently. + +Published to npm as `capiscio`. Users install via `npm install -g capiscio`. + +**Technology Stack**: TypeScript, Node.js, npm + +**Current Version**: v2.4.0 +**Default Branch:** `main` + +## Architecture + +This is a **thin passthrough wrapper**, NOT a reimplementation. All logic lives in capiscio-core. + +``` +capiscio-node/ +├── src/ +│ ├── cli.ts # Main entry point - parses args, delegates to binary +│ ├── index.ts # Library exports +│ └── utils/ +│ └── binary-manager.ts # Downloads + caches platform-specific capiscio-core binary +├── bin/ +│ └── capiscio.js # npm bin entry point +└── package.json # npm package config (name: "capiscio") +``` + +### How It Works + +1. User runs `capiscio verify agent-card.json` +2. `cli.ts` invokes `BinaryManager` to ensure Go binary is downloaded +3. Binary is cached in OS-specific cache dir +4. All args are passed through to the Go binary via `execa` + +## Quick Commands + +```bash +pnpm install # Install deps +pnpm build # Compile TypeScript +pnpm test # Run tests +pnpm dev # Dev mode +``` + +## Critical Rules + +- **Never add CLI logic here** — all commands belong in capiscio-core +- Binary downloads use GitHub Releases from `capiscio/capiscio-core` +- Platform detection: `process.platform` + `process.arch` +- Version must stay aligned with capiscio-core + +## Publishing + +npm publish is triggered by creating a GitHub Release (NOT just a tag push). +```bash +git tag v2.4.1 && git push origin v2.4.1 +gh release create v2.4.1 --title "v2.4.1" # THIS triggers npm publish +``` From bbbf6dd4ee9bedbf7b36aeba3a6dd97276898950 Mon Sep 17 00:00:00 2001 From: Beon de Nood Date: Fri, 27 Feb 2026 14:35:01 -0500 Subject: [PATCH 2/2] fix: address copilot review comments on instructions - Replace pnpm with npm (repo uses package-lock.json, not pnpm-lock.yaml) - Clarify watch commands OK for interactive dev, not automation - Add conditional check for workspace context files (may not exist) - Clarify version alignment: CORE_VERSION tracks core binary, npm version can differ - Fix publish guidance: release must be published (not draft/prerelease) - Fix cache dir: installed to /bin or ~/.capiscio/bin - Fix platform detection: os.platform()/os.arch(), not process.platform/arch - Fix CLI command: validate, not verify --- .github/copilot-instructions.md | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 758bf06..d3e94b0 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -6,19 +6,22 @@ - **NEVER commit directly to `main`.** All changes MUST go through PRs. ### 2. LOCAL CI VALIDATION BEFORE PUSH -- Run: `pnpm test` and `pnpm build` +- Run: `npm test` and `npm run build` ### 3. NO WATCH/BLOCKING COMMANDS -- **NEVER run blocking commands** without timeout +- **NEVER run blocking commands in automation** without timeout +- Watch commands (`npm run dev`, `npm run test:watch`) are fine for interactive local dev --- ## CRITICAL: Read First -**Before starting work, read the workspace context files:** +**If working inside the CapiscIO monorepo workspace that includes `.context/`, read these workspace context files before starting work:** 1. `../../.context/CURRENT_SPRINT.md` - Sprint goals and priorities 2. `../../.context/ACTIVE_TASKS.md` - Active tasks +If these files are not present in your checkout of this repository, skip this step. + --- ## Repository Purpose @@ -28,9 +31,9 @@ the platform-specific Go binary and passes all commands through transparently. Published to npm as `capiscio`. Users install via `npm install -g capiscio`. -**Technology Stack**: TypeScript, Node.js, npm +**Technology Stack**: TypeScript, Node.js, npm (NOT pnpm — this repo uses package-lock.json) -**Current Version**: v2.4.0 +**Current Version**: v2.4.0 (wrapper); core binary version is controlled by `DEFAULT_VERSION` in `binary-manager.ts` **Default Branch:** `main` ## Architecture @@ -51,31 +54,31 @@ capiscio-node/ ### How It Works -1. User runs `capiscio verify agent-card.json` +1. User runs `capiscio validate agent-card.json` 2. `cli.ts` invokes `BinaryManager` to ensure Go binary is downloaded -3. Binary is cached in OS-specific cache dir +3. Binary is installed to `/bin` (or falls back to `~/.capiscio/bin`) 4. All args are passed through to the Go binary via `execa` ## Quick Commands ```bash -pnpm install # Install deps -pnpm build # Compile TypeScript -pnpm test # Run tests -pnpm dev # Dev mode +npm install # Install deps +npm run build # Compile TypeScript +npm test # Run tests +npm run dev # Dev mode (watch - interactive only) ``` ## Critical Rules - **Never add CLI logic here** — all commands belong in capiscio-core - Binary downloads use GitHub Releases from `capiscio/capiscio-core` -- Platform detection: `process.platform` + `process.arch` -- Version must stay aligned with capiscio-core +- Platform detection: `os.platform()` + `os.arch()`, mapped to `darwin/linux/windows` and `amd64/arm64` +- The `CORE_VERSION` constant in `src/utils/binary-manager.ts` must track the capiscio-core release tag used for the downloaded binary; the npm package version can differ ## Publishing -npm publish is triggered by creating a GitHub Release (NOT just a tag push). +npm publish is triggered by creating a **published** GitHub Release (NOT just a tag push). Draft or prerelease releases will **not** trigger npm publish. ```bash git tag v2.4.1 && git push origin v2.4.1 -gh release create v2.4.1 --title "v2.4.1" # THIS triggers npm publish +gh release create v2.4.1 --title "v2.4.1" # Creates a PUBLISHED release, which triggers npm publish ```