{"_id":"@aethrekh/pisces-cli","name":"@aethrekh/pisces-cli","dist-tags":{"beta":"0.1.0-beta.0","latest":"0.1.0-beta.0"},"versions":{"0.1.0-beta.0":{"name":"@aethrekh/pisces-cli","version":"0.1.0-beta.0","description":"Pisces CLI — /pisces workspace lifecycle commands for Pi Coding Agent","keywords":["pisces","cli","pi","pi-package"],"author":{"name":"Ashish Bagdane","email":"ashishbagdane1@gmail.com"},"license":"UNLICENSED","main":"dist/index.js","types":"dist/index.d.ts","publishConfig":{"access":"public"},"scripts":{"build":"tsc --project tsconfig.json","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","typecheck":"tsc --project tsconfig.json --noEmit","check":"pnpm run typecheck && pnpm run lint && pnpm run test:coverage","validate":"npx ts-node --project tsconfig.json scripts/validate.ts","pack":"npx ts-node --project tsconfig.json scripts/pack.ts"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"devDependencies":{"@earendil-works/pi-coding-agent":"*","@types/jest":"^29.5.14","@types/node":"^20.17.6","jest":"^29.7.0","ts-jest":"^29.2.5","typescript":"^5.6.3"},"engines":{"node":">=18.0.0"},"gitHead":"35e220e8a83a1632d3ea7d8a04a63e6adbd995ab","_id":"@aethrekh/pisces-cli@0.1.0-beta.0","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-Zbherb866KO5VeGuool5xnYdbcKKnqZ0TQbVODgQXL4a5OFmIxgzk0ztQZZl2a7kyuZ3gZEsmhZ6L1FCYV23pQ==","shasum":"ec954e6e8b4abeb4d1eacea7c17dbd0c1a67f985","tarball":"https://registry.npmjs.org/@aethrekh/pisces-cli/-/pisces-cli-0.1.0-beta.0.tgz","fileCount":21,"unpackedSize":25555,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIB1vpTAJkGLK4yXtK7L4cvNVku9UFLvg+jtebN9LXE/iAiAOQ7wWI5p0iTFCC+qdp0j+lOg4+wxTTx9t9Ov05C2slg=="}]},"_npmUser":{"name":"aethrekh","email":"tech@aethrekh.com"},"directories":{},"maintainers":[{"name":"aethrekh","email":"tech@aethrekh.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pisces-cli_0.1.0-beta.0_1787291830724_0.06658930858398282"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-21T05:57:10.511Z","0.1.0-beta.0":"2026-08-21T05:57:10.851Z","modified":"2026-08-21T05:57:11.126Z"},"maintainers":[{"name":"aethrekh","email":"tech@aethrekh.com"}],"description":"Pisces CLI — /pisces workspace lifecycle commands for Pi Coding Agent","keywords":["pisces","cli","pi","pi-package"],"author":{"name":"Ashish Bagdane","email":"ashishbagdane1@gmail.com"},"license":"UNLICENSED","readme":"# `@aethrekh/pisces-cli`\n\nWorkspace lifecycle commands for [Pi Coding Agent](https://github.com/earendil-works/pi). Registers the `/pisces` command with five flags: `--activate`, `--deactivate`, `--status`, `--setup`, and `--doctor`.\n\nThis package is the user-facing complement to [`@aethrekh/pisces-core`](../core). Core owns skill gating and evaluation; CLI owns everything a learner types to manage their workspace.\n\n---\n\n## Installation\n\nInstall alongside `pisces-core` — both are needed for the full experience:\n\n```bash\npi install npm:@aethrekh/pisces-core\npi install npm:@aethrekh/pisces-cli\n```\n\n---\n\n## Commands\n\nAll commands are accessed via `/pisces <flag>` inside a Pi session.\n\n### `/pisces --status`\n\nShows the current workspace state. No side effects.\n\n**When inactive:**\n```\nPisces  ✗ Not Active\n────────────────────\nNo .pisces workspace marker found.\n(searched up from /Users/you/projects/lab1)\n\nNext step\n─────────\nNavigate to your workspace folder, then run:\n\n  /pisces --activate   Create workspace here\n  /pisces --setup      Guided setup (recommended)\n```\n\n**When active:**\n```\nPisces  ✓ Active\n────────────────────\nWorkspace   /Users/you/my-project\n             (2 levels inside)\n\nSkills:\n  /attempt\n```\n\nRunning `/pisces` with no flag is equivalent to `--status`.\n\n---\n\n### `/pisces --activate`\n\nCreates a `.pisces` marker file in the current directory and reloads Pi so skills become available immediately.\n\nBefore creating the marker, Pisces walks up the directory tree looking for a directory whose name matches a workspace root pattern (`university`, `uni`, `college`, `school`, `cs`, `fall2025`, `spring2025`, etc.). If a better root is found, it is offered as an alternative:\n\n```\nBetter root found: /Users/you/university\nActivate there instead of /Users/you/university/fall2025/CS301? [y/N]\n```\n\nChoosing `y` creates `.pisces` at the suggested root so all subdirectories inherit workspace activation. Choosing `n` (or entering nothing) creates it at the current directory.\n\nAfter activation Pi reloads automatically.\n\n---\n\n### `/pisces --deactivate`\n\nRemoves the `.pisces` marker from the nearest workspace root above the current directory.\n\n```\nDeactivate workspace at /Users/you/my-project? [y/N]\n```\n\nRequires confirmation before deleting. After deactivation Pi reloads and skills are suppressed.\n\n---\n\n### `/pisces --setup`\n\nGuided first-time setup. Walks through:\n\n1. **Prerequisites check** — Node.js version ≥ 18, `pisces-core` installed.\n2. **Workspace activation** — if not already active, offers to run `--activate`.\n3. **Post-activation** — confirms setup is complete and shows the `--status` output.\n\nRecommended for first-time users. Equivalent to running `--doctor` + `--activate` with guided prompts.\n\n---\n\n### `/pisces --doctor`\n\nHealth check. Reports on:\n\n| Check | Pass condition |\n|---|---|\n| Pisces CLI loaded | Extension registered successfully |\n| Node.js version | `>= 18.0.0` |\n| Workspace active | `.pisces` found at or above `cwd` |\n| Stale system prompt | `~/.pi/agent/APPEND_SYSTEM.md` exists and is current |\n\nExample output:\n\n```\nPisces Doctor\n─────────────────────────────\n✓  Pisces CLI loaded\n✓  Node.js v20.11.0 (≥ 18 required)\n✗  Workspace not active\n     Run /pisces --activate to enable skills here.\n✓  System prompt installed\n```\n\n---\n\n## Workspace detection\n\nThe CLI reads workspace state from `pisces-core`'s `syncWorkspaceState()` and `findWorkspace()` utilities. On `resources_discover`, the CLI syncs the state cache so all command handlers see a consistent view.\n\nDetection algorithm:\n\n1. Start from Pi's working directory (`cwd` from the `resources_discover` event).\n2. Walk up the directory tree, checking for a `.pisces` file at each level.\n3. Stop at the user's home directory or after 15 levels, whichever comes first.\n4. Cache the result for the session — mid-session `cd` does not re-trigger detection.\n\n---\n\n## Inactive workspace nudge\n\nWhen Pi starts in a directory without `.pisces`, the CLI fires a `session_start` notification:\n\n```\n✓ Pisces is installed  ·  ✗ Not active here\n\nSkills are off until you activate a workspace.\n\n  /pisces --activate   Mark this directory as your workspace\n  /pisces --setup      Guided first-time setup (recommended)\n  /pisces --status     See what Pisces detects\n```\n\nThe status bar also updates to show `🐠 Pisces · not active` in a muted style.\n\nIf the workspace is active, the nudge is suppressed entirely — no noise in active sessions.\n\n---\n\n## Skill redirect stubs\n\nThe CLI registers stub commands for every Pisces skill name (`attempt`). This means learners get a helpful redirect rather than Pi's \"unknown command\" error when they try to use a skill in an inactive workspace:\n\n```\n🐠 Pisces: /attempt is available but the workspace isn't active here.\n\n  /pisces --activate   Enable skills in this directory\n  /pisces --setup      Guided setup (recommended for first time)\n```\n\nWhen the workspace is active, the stub redirects to `/skill:attempt` (the proper Pi skill invocation path).\n\n---\n\n## Package scripts\n\n```bash\npnpm build           # Compile src/ → dist/\npnpm test            # Run Jest test suite\npnpm test:coverage   # With coverage (70% branch / 80% line thresholds)\npnpm typecheck       # Type-check without emit\npnpm lint            # ESLint over src/\npnpm check           # typecheck + lint + test:coverage (CI gate)\n```\n\n---\n\n## Architecture\n\n```\npackages/cli/\n├── pi-package.yaml           # Pi runtime manifest (triggers: resources_discover, session_start)\n└── src/\n    ├── index.ts              # Pi extension factory — registers /pisces and skill stubs\n    ├── commands/\n    │   ├── activate.ts       # --activate: create .pisces, suggest parent root, reload\n    │   ├── deactivate.ts     # --deactivate: remove .pisces with confirmation, reload\n    │   ├── status.ts         # --status: show workspace state and available skills\n    │   ├── setup.ts          # --setup: guided first-time walkthrough\n    │   └── doctor.ts         # --doctor: health checks with pass/fail output\n    └── lib/\n        ├── suggest-root.ts   # Walk up for university-named ancestors\n        └── ui.ts             # Shared UI primitives (SEP, row, skillsList)\n```\n\n---\n\n## Peer dependencies\n\n| Package | Role |\n|---|---|\n| `@earendil-works/pi-coding-agent` | Pi runtime types (`ExtensionAPI`, `ExtensionCommandContext`) |\n| `@aethrekh/pisces-core` | Workspace detection (`findWorkspace`, `syncWorkspaceState`, `getWorkspaceState`) |\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-1ee2b45172375052588435be164e3f26"}