From e3c84c57941a7ad848063e41fb3c032f6f7bf3d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= Date: Sat, 6 Jun 2026 14:03:24 +0000 Subject: [PATCH] =?UTF-8?q?chore:=20rename=20prompt=20setup=E2=86=92bootst?= =?UTF-8?q?rap,=20programmatic=20generation,=20bun=E2=86=92pnpm=20cleanup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part 1: Rename 'ocas prompt setup' → 'ocas prompt bootstrap' in CLI Part 2: Replace static setup.md with cmdPromptBootstrap() function - CLI_VERSION injected dynamically (same pattern as uwf) - Covers fresh install + upgrade scenarios - Includes preflight checks, skill install, e2e verification Part 3: Clean up bun references in workflow YAML files - .workflows/retrospect-workflow.yaml: bun→pnpm - .workflows/solve-issue.yaml: bun→pnpm - .workflows/e2e-check.yaml: archived to legacy-packages/ Fixes #80 小橘 🍊 --- .workflows/retrospect-workflow.yaml | 10 +- .workflows/solve-issue.yaml | 12 +- .../workflows}/e2e-check.yaml | 0 packages/cli/prompts/setup.md | 53 ----- packages/cli/src/index.ts | 15 +- packages/cli/src/prompt-bootstrap.ts | 183 ++++++++++++++++++ .../__snapshots__/edge-cases.test.ts.snap | 2 +- 7 files changed, 202 insertions(+), 73 deletions(-) rename {.workflows => legacy-packages/workflows}/e2e-check.yaml (100%) delete mode 100644 packages/cli/prompts/setup.md create mode 100644 packages/cli/src/prompt-bootstrap.ts diff --git a/.workflows/retrospect-workflow.yaml b/.workflows/retrospect-workflow.yaml index 820153f..3235bf7 100644 --- a/.workflows/retrospect-workflow.yaml +++ b/.workflows/retrospect-workflow.yaml @@ -120,15 +120,15 @@ roles: 1. Use `git rev-parse --show-toplevel` to find the repo root (do NOT use repoPath from proposer — that's the analyzed repo) 2. `git fetch origin` to get latest refs 3. `git worktree add .worktrees/retrospect/ -b retrospect/ origin/main` - 4. `cd .worktrees/retrospect/ && bun install` + 4. `cd .worktrees/retrospect/ && pnpm install` 5. ALL subsequent work must happen inside the worktree directory. Then apply changes: 6. Read the change plan from CAS: `uwf cas get ` 7. Apply each edit from the plan to the workflow YAML 8. Update or add tests as specified in the plan - 9. Run `bun run build` and `bun test` to verify - 10. Run `bun run check` for lint + 9. Run `pnpm run build` and `pnpm test` to verify + 10. Run `pnpm run check` for lint 11. Commit with message: `improve: — ` output: "List all files changed and provide a summary. Set $status to done (with branch/worktree), or failed (with reason)." frontmatter: @@ -157,8 +157,8 @@ roles: 2. Edits should be minimal — don't rewrite working procedures 3. New pitfall notes or instructions must be clear and actionable 4. Tests must be updated if assertions changed - 5. `bun run build` and `bun test` must pass - 6. `bunx biome check` must pass + 5. `pnpm run build` and `pnpm test` must pass + 6. `pnpm run check` must pass IMPORTANT: `tea pr create` must run from the MAIN repo directory (not a worktree), because tea cannot detect the repo from worktree `.git` files. output: "Explain your decision. Set $status to approved (with branch/worktree) or rejected (with comments)." diff --git a/.workflows/solve-issue.yaml b/.workflows/solve-issue.yaml index 347beb1..62692f3 100644 --- a/.workflows/solve-issue.yaml +++ b/.workflows/solve-issue.yaml @@ -50,7 +50,7 @@ roles: 2. `git fetch origin` to get latest refs 3. First time (no existing branch): - `git worktree add .worktrees/fix/- -b fix/- origin/main` - - `cd .worktrees/fix/- && bun install` + - `cd .worktrees/fix/- && pnpm install` 4. If bounced back from reviewer or tester (branch already exists): - cd into the existing worktree under `.worktrees/fix/-` - `git fetch origin && git rebase origin/main` @@ -61,8 +61,8 @@ roles: 7. If bounced back from reviewer or tester: read the previous role's feedback in your task prompt 8. Write tests first based on the spec 9. Implement the code to make tests pass - 10. Ensure `bun run build` passes with no errors - 11. Run `bun test` to verify all tests pass + 10. Ensure `pnpm run build` passes with no errors + 11. Run `pnpm test` to verify all tests pass If you cannot complete the implementation (e.g. the issue is too complex, blocked by external factors, or repeated attempts fail), set $status=failed with a reason. @@ -95,8 +95,8 @@ roles: Then perform code review: Hard checks (must all pass): - 3. `bun run build` — no build errors - 4. `bunx biome check` — no lint violations + 3. `pnpm run build` — no build errors + 4. `pnpm run check` — no lint violations 5. TypeScript strict mode — no type errors Soft checks (review against project conventions if CLAUDE.md / .cursor/rules exist): @@ -129,7 +129,7 @@ roles: procedure: | The worktree path is provided in your task prompt. cd into it first. - 1. Run `bun test` for automated test verification + 1. Run `pnpm test` for automated test verification 2. Read the test spec from CAS: `uwf cas get ` (find the hash from the planner step in the thread history) 3. Verify each scenario in the spec is covered and passing 4. Determine outcome: diff --git a/.workflows/e2e-check.yaml b/legacy-packages/workflows/e2e-check.yaml similarity index 100% rename from .workflows/e2e-check.yaml rename to legacy-packages/workflows/e2e-check.yaml diff --git a/packages/cli/prompts/setup.md b/packages/cli/prompts/setup.md deleted file mode 100644 index 26a3fad..0000000 --- a/packages/cli/prompts/setup.md +++ /dev/null @@ -1,53 +0,0 @@ -# OCAS Skill Setup - -You are being asked to install or update the OCAS (Object Content Addressable Store) skill -so that you know how to use the `ocas` CLI. - -## Steps - -1. **Check if OCAS CLI is installed:** - ```bash - ocas --help - ``` - If not installed: `pnpm add -g @ocas/cli` - -2. **Clean up old versions of the skill** (if any exist): - - Look for any existing OCAS/ocas skill files in your skill directories - (e.g. `~/.hermes/skills/ocas/SKILL.md` or similar paths). - - If a skill exists, read its `version` from the YAML frontmatter. - - If the version matches the current CLI version (`ocas --version`), you're done — no update needed. - - If the version is older, **delete the old skill file** before proceeding. - -3. **Get the usage skill content:** - ```bash - ocas prompt usage - ``` - -4. **Create a SKILL.md file** in your skill directory (e.g. `~/.hermes/skills/ocas/SKILL.md`). - The output of `ocas prompt usage` is the skill body WITHOUT frontmatter. - You must prepend the following YAML frontmatter: - - ```yaml - --- - name: ocas - description: "Use when storing, retrieving, or managing typed JSON data with OCAS (Object Content Addressable Store). Covers CLI usage, variable management, templates, rendering, and pipe composition." - version: - author: OCAS - license: MIT - metadata: - hermes: - tags: [cas, storage, cli, json, schema, content-addressing] - --- - ``` - - Replace `` with the installed CLI version (from `ocas --version`). - -5. **Verify** the skill is loadable by your agent framework. - -## Notes - -- The skill content is bundled with the CLI and versioned with it — always use - `ocas prompt usage` to get the content matching your installed version. -- Do NOT hand-edit the skill body. If the CLI is updated, re-run `ocas prompt setup` - and follow the steps again. -- When upgrading, always delete the old skill first to avoid stale instructions. diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 385e32c..6b3eeed 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -5,6 +5,8 @@ import { homedir } from "node:os"; import { dirname, join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; +import { cmdPromptBootstrap } from "./prompt-bootstrap.js"; + const __dirname = dirname(fileURLToPath(import.meta.url)); import type { Hash, ListEntry, ListOptions, Store, TagOp } from "@ocas/core"; @@ -1115,7 +1117,7 @@ Flags: --epsilon Cutoff threshold for render (default: 0.01) --pipe, -p Read from stdin (put/hash: raw JSON payload; render: { type, value } envelope) -Agent: If you have not installed the ocas skill for this version (${pkg.version}), run \`ocas prompt setup\` and follow the instructions.`); +Agent: If you have not installed the ocas skill for this version (${pkg.version}), run \`ocas prompt bootstrap\` and follow the instructions.`); } // ---- Dispatch ---- @@ -1240,17 +1242,14 @@ switch (cmd) { process.stdout.write(content); break; } - case "setup": { - const content = readFileSync( - join(__dirname, "..", "prompts", "setup.md"), - "utf-8", - ); - process.stdout.write(content); + case "bootstrap": { + // biome-ignore lint/suspicious/noConsole: CLI user-facing output + console.log(cmdPromptBootstrap()); break; } default: die( - `Unknown prompt subcommand: ${sub ?? "(none)"}. Available: usage, setup`, + `Unknown prompt subcommand: ${sub ?? "(none)"}. Available: usage, bootstrap`, ); } break; diff --git a/packages/cli/src/prompt-bootstrap.ts b/packages/cli/src/prompt-bootstrap.ts new file mode 100644 index 0000000..0818b5d --- /dev/null +++ b/packages/cli/src/prompt-bootstrap.ts @@ -0,0 +1,183 @@ +import { readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; + +// Walk up from __dirname to find the nearest @ocas/cli package.json +function _findCliVersion(): string { + let dir = dirname(fileURLToPath(import.meta.url)); + for (let i = 0; i < 5; i++) { + const candidate = join(dir, "package.json"); + try { + const pkg = JSON.parse(readFileSync(candidate, "utf-8")) as { + name?: string; + version?: string; + }; + if (pkg.name === "@ocas/cli") { + return pkg.version ?? "0.0.0"; + } + } catch { + // not found, keep walking + } + dir = dirname(dir); + } + return "0.0.0"; +} + +const CLI_VERSION = _findCliVersion(); + +export function cmdPromptBootstrap(): string { + return `# ocas Bootstrap + +Set up or upgrade ocas (Object Content Addressable Store) — from zero to running your first command. + +## Scenario A: Fresh Install + +### Step 0 — Environment pre-flight check + +Run ALL checks below BEFORE installing anything. If any check fails, fix it first — do NOT skip ahead. + +\`\`\`bash +# 1. Node.js +node --version # need v20+ +# FIX: install via nvm (https://github.com/nvm-sh/nvm) or your OS package manager + +# 2. Package manager — pnpm (preferred) or npm +pnpm --version || npm --version +# FIX for pnpm: corepack enable pnpm (Node 20+) +# or: npm install -g pnpm +# If pnpm is not an option, npm works too — adjust install commands below + +# 3. Global bin directory is in PATH +# For pnpm: +pnpm bin -g # prints the global bin directory +# For npm: +npm prefix -g # global prefix; bin is /bin +# The directory printed above MUST be in your PATH. +# Test: echo \\$PATH | tr ':' '\\n' +# FIX: add the missing directory to your shell's startup file +# (e.g. ~/.bashrc, ~/.zshrc, ~/.profile, or fish config): +# export PATH=":$PATH" +\`\`\` + +**All checks must pass before continuing.** If you had to modify PATH, verify the change persists by opening a new shell or sourcing your shell config. + +### Step 1 — Install @ocas/cli + +\`\`\`bash +# Using pnpm (preferred) +pnpm add -g @ocas/cli + +# Using npm +npm install -g @ocas/cli +\`\`\` + +**After installing, verify that \`ocas\` is available in PATH:** + +\`\`\`bash +ocas --version # should print ${CLI_VERSION} +\`\`\` + +If the command is not found, the global bin directory is not in the current shell's PATH. **You must fix this before continuing:** + +1. Find where the binary was installed: + \`\`\`bash + find ~/.local /usr/local -name ocas -type f 2>/dev/null + npm prefix -g # global prefix — bin is /bin + \`\`\` +2. Add the directory to PATH permanently by appending to the user's shell config (e.g. \`~/.bashrc\`, \`~/.zshrc\`, \`~/.profile\`, or fish config): + \`\`\`bash + export PATH=":$PATH" + \`\`\` +3. Source the updated config or open a new shell, then re-verify the command works. + +### Step 2 — Verify version + +\`\`\`bash +ocas --version # should print ${CLI_VERSION} +\`\`\` + +### Step 3 — Install the ocas skill + +Run the usage prompt and save it as a skill so your agent knows how to use ocas: + +\`\`\`bash +ocas prompt usage +\`\`\` + +The output is the skill body **without** frontmatter. Save it as a skill in your agent framework with the following YAML frontmatter prepended: + +\`\`\`yaml +--- +name: ocas +description: "Use when storing, retrieving, or managing typed JSON data with OCAS (Object Content Addressable Store). Covers CLI usage, variable management, templates, rendering, and pipe composition." +version: ${CLI_VERSION} +author: OCAS +license: MIT +metadata: + hermes: + tags: [cas, storage, cli, json, schema, content-addressing] +--- +\`\`\` + +Replace the \`version\` field with the installed CLI version (from \`ocas --version\`). + +**⚠ After saving the skill, start a new session** so the agent loads the updated skill content. Skills saved in the current session are not active until the next session. + +### Step 4 — End-to-end verify + +\`\`\`bash +# Store a string value +ocas put @ocas/string '"hello world"' + +# Get it back using the returned hash +ocas get +\`\`\` + +If \`ocas get\` returns \`"hello world"\`, the setup is working. + +## Scenario B: Upgrade from Previous Version + +### Step 1 — Update to latest + +\`\`\`bash +# Using pnpm +pnpm add -g @ocas/cli@latest + +# Using npm +npm install -g @ocas/cli@latest +\`\`\` + +### Step 2 — Verify version + +\`\`\`bash +ocas --version # should print ${CLI_VERSION} +\`\`\` + +### Step 3 — Regenerate skill + +Skill content is bundled with the CLI — always regenerate after upgrading: + +\`\`\`bash +ocas prompt usage # → update skill "ocas" +\`\`\` + +Update the \`version\` field in the skill frontmatter to match the new CLI version. + +**⚠ After updating the skill, start a new session** to load the new skill content. + +### Step 4 — Verify + +\`\`\`bash +ocas put @ocas/string '"upgrade test"' +ocas get +\`\`\` + +## Available prompts + +\`\`\`bash +ocas prompt list # list available prompt names +ocas prompt usage # CLI usage guide (skill body) +ocas prompt bootstrap # this guide +\`\`\` +`; +} diff --git a/packages/cli/tests/__snapshots__/edge-cases.test.ts.snap b/packages/cli/tests/__snapshots__/edge-cases.test.ts.snap index 6712568..c21afe8 100644 --- a/packages/cli/tests/__snapshots__/edge-cases.test.ts.snap +++ b/packages/cli/tests/__snapshots__/edge-cases.test.ts.snap @@ -466,5 +466,5 @@ Flags: --epsilon Cutoff threshold for render (default: 0.01) --pipe, -p Read from stdin (put/hash: raw JSON payload; render: { type, value } envelope) -Agent: If you have not installed the ocas skill for this version (0.3.1), run \`ocas prompt setup\` and follow the instructions." +Agent: If you have not installed the ocas skill for this version (0.3.1), run \`ocas prompt bootstrap\` and follow the instructions." `;