@pathmode/cli 2.0.0 → 2.0.1

package/README.md

@@ -1,38 +1,202 @@
-# IntentSpec Validation Action
+# @pathmode/cli
 
-The official GitHub Action for [IntentSpec](https://intentspec.org) — the open standard for Spec-Driven Development.
+The command-line interface for [Pathmode](https://pathmode.io). It syncs your repo's agent context files with your Pathmode workspace, pushes implementation status back, and validates specs against the [IntentSpec](https://intentspec.org/spec) standard.
 
-Use this action to enforce **Functional Guardrails** in your CI/CD pipeline. It validates that your `intent.md` exists and adheres to the [IntentSpec Schema](https://intentspec.org/schema.json).
+## Install
 
-## Usage
+```bash
+npm i -g @pathmode/cli
+```
+
+This installs the `pathmode` binary. Check it with:
+
+```bash
+pathmode --version
+```
+
+You can also run it without installing:
+
+```bash
+npx @pathmode/cli validate
+```
+
+## Quick start
+
+```bash
+npm i -g @pathmode/cli
+pathmode login          # paste your pm_live_ API key
+pathmode init           # write intent.md, .cursorrules, CLAUDE.md
+```
+
+`validate` works with no account. The other five commands talk to the Pathmode API and need a key.
+
+## Authentication
+
+1. Open your Pathmode workspace, go to **Workspace Settings > API Keys**, and create a key. Keys start with `pm_live_`.
+2. Run `pathmode login`. With no flags it prompts for the key and workspace ID, verifies them against the API, and reports the workspace it connected to.
+
+```bash
+pathmode login
+# or non-interactively:
+pathmode login --key pm_live_xxx --workspace <workspace-id>
+```
+
+Credentials are written to `~/.pathmode/config.json` with `0600` permissions.
+
+### Environment variables
+
+Environment variables take precedence over the config file, so use them in CI instead of committing a config:
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `PATHMODE_API_KEY` | API key (`pm_live_...`) | none |
+| `PATHMODE_API_URL` | API base URL | `https://pathmode.io` |
+| `PATHMODE_WORKSPACE_ID` | Workspace ID | none |
+
+## Commands
+
+| Command | What it does | Needs auth |
+|---|---|---|
+| [`validate`](#validate-file) | Check a spec against the IntentSpec schema | No |
+| [`login`](#login) | Store and verify your API key | Sets it up |
+| [`init`](#init) | Scaffold intent files in a fresh repo | Yes |
+| [`pull`](#pull) | Refresh local context files from the workspace | Yes |
+| [`push`](#push) | Send status changes and notes back | Yes |
+| [`status`](#status) | List workspace intents and their status | Yes |
+
+### `validate [file]`
+
+Validates the YAML frontmatter of a markdown file against the [IntentSpec schema](https://intentspec.org/schema.json). Exits `0` when valid and `1` when not, printing each failed field, so it works as a CI gate.
+
+```bash
+pathmode validate                 # defaults to intent.md
+pathmode validate specs/login.md
+```
+
+Required fields are `id`, `status`, `objective`, and `outcomes`. `status` must be one of `draft`, `validated`, `approved`, `shipped`, or `verified`. See the [full standard](https://intentspec.org/spec) for the optional fields.
+
+### `login`
+
+| Option | Description | Default |
+|---|---|---|
+| `--key <key>` | API key, starting with `pm_live_` | prompts |
+| `--workspace <id>` | Workspace ID | prompts |
+| `--url <url>` | Pathmode API URL | `https://pathmode.io` |
+
+If the connection test fails the config is still saved, so you can fix the network and retry with `pathmode pull`.
+
+### `init`
+
+Pulls your workspace context and writes three files into the current directory:
+
+- `intent.md`, the current intent spec
+- `.cursorrules`, rules for Cursor
+- `CLAUDE.md`, workspace context for Claude Code
 
-Add this to your workflow file (e.g., `.github/workflows/intentspec.yml`):
+```bash
+pathmode init
+pathmode init --dry-run           # preview without writing
+pathmode init --intent abc-123    # use a specific intent
+```
+
+| Option | Description |
+|---|---|
+| `--intent <id>` | Use a specific intent instead of the current approved one |
+| `--dry-run` | Print what would be written and exit |
+
+### `pull`
+
+Re-syncs the files `init` created. Run it whenever the spec changes upstream.
+
+```bash
+pathmode pull
+pathmode pull --only claude-md,intent-md
+pathmode pull --only agents-md
+```
+
+| Option | Description |
+|---|---|
+| `--intent <id>` | Pull a specific intent |
+| `--only <files>` | Comma-separated subset of `claude-md`, `agents-md`, `cursorrules`, `intent-md` |
+
+`AGENTS.md` is opt-in. It carries the same context as `CLAUDE.md`, so syncing it by default would only duplicate that file. Request it with `--only agents-md` if you use OpenAI Codex or a recent Cursor version.
+
+### `push`
+
+Reports progress back to the workspace. The intent ID comes from the `id` in your local `intent.md` frontmatter unless you pass `--intent`.
+
+```bash
+pathmode push --shipped
+pathmode push --verified
+pathmode push --note "Rate limiting added in middleware, not the route handler"
+```
+
+| Option | Description |
+|---|---|
+| `--shipped` | Mark the intent as shipped |
+| `--verified` | Mark the intent as verified |
+| `--note <text>` | Log an implementation note against the intent |
+| `--intent <id>` | Target a specific intent |
+
+### `status`
+
+Lists the workspace's intents with their status, severity, and stage.
+
+```bash
+pathmode status
+pathmode status --filter approved
+```
+
+| Option | Description |
+|---|---|
+| `--filter <status>` | One of `draft`, `validated`, `approved`, `shipped`, `verified` |
+
+## How CLAUDE.md is updated
+
+`init` and `pull` do not overwrite `CLAUDE.md` or `AGENTS.md`. They replace only the block between these markers, leaving your own notes and conventions intact:
+
+```markdown
+<!-- PATHMODE:START - Do not edit this section manually -->
+... generated content ...
+<!-- PATHMODE:END -->
+```
+
+If the markers are absent the section is appended. `.cursorrules` and `intent.md` are fully replaced on every sync.
+
+## Using it in CI
+
+Validate every spec on a pull request:
+
+```yaml
+- uses: actions/checkout@v4
+- run: npx @pathmode/cli validate intent.md
+```
+
+Keep context files fresh on a schedule, using repository secrets for the credentials:
 
 ```yaml
-name: Validate IntentSpec
+- run: npm i -g @pathmode/cli
+- run: pathmode pull
+  env:
+    PATHMODE_API_KEY: ${{ secrets.PATHMODE_API_KEY }}
+    PATHMODE_WORKSPACE_ID: ${{ secrets.PATHMODE_WORKSPACE_ID }}
+```
 
-on: [push, pull_request]
+This package also ships an `action.yml`, so the same bundle runs directly as a GitHub Action that validates a spec. It reads the `file` input, defaulting to `intent.md`.
 
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      
-      - name: Validate Intent Spec
-        uses: JanneL/validate-intentspec-action@v1
-        with:
-          file: 'intent.md' # Optional (default: intent.md)
+```yaml
+- uses: JanneL/validate-intentspec-action@v1
+  with:
+    file: 'intent.md'
 ```
 
-## Inputs
+## IntentSpec
+
+`validate` checks against IntentSpec, the open standard for describing what a change is supposed to accomplish before an agent writes the code.
 
-| Input | Description | Default | Required |
-| :--- | :--- | :--- | :--- |
-| `file` | Path to the intent markdown file | `intent.md` | No |
+- Standard: <https://intentspec.org/spec>
+- JSON Schema: <https://intentspec.org/schema.json>
 
-## Why use this?
+## License
 
-1.  **Prevent Drift:** Ensure AI agents (and humans) have a clear definition of "Done".
-2.  **Enforce Structure:** Validate that `objective`, `outcomes`, and `constraints` are defined.
-3.  **Governance:** Make IntentSpecs a required part of your PR process.
+MIT

package/dist/index.js

@@ -11150,6 +11150,11 @@ class PathmodeClient {
         const res = await this.fetch('/export?format=claude-md');
         return res.text();
     }
+    /** Export AGENTS.md content (same workspace context as CLAUDE.md, for Codex / modern Cursor) */
+    async exportAgentsMd() {
+        const res = await this.fetch('/export?format=agents-md');
+        return res.text();
+    }
     /** Export .cursorrules content */
     async exportCursorRules(intentId) {
         const params = intentId ? `?format=cursorrules&intent_id=${intentId}` : '?format=cursorrules';
@@ -11207,7 +11212,7 @@ const isGitHubAction = !!process.env.GITHUB_ACTIONS || !!process.env.INPUT_FILE;
 program
     .name('pathmode')
     .description('Pathmode CLI — Intent Engineering for AI product teams')
-    .version('2.0.0');
+    .version('2.0.1');
 // ============================================================
 // validate — Existing command (preserved)
 // ============================================================
@@ -11353,7 +11358,7 @@ program
         console.log(chalk_1.default.green(`\u2705 Written: ${cursorPath}`));
         // Write or update CLAUDE.md
         const claudePath = path_1.default.join(cwd, 'CLAUDE.md');
-        writeClaudeMdSection(claudePath, claudeMd);
+        writePathmodeSection(claudePath, claudeMd);
         console.log(chalk_1.default.green(`\u2705 Written: ${claudePath}`));
         console.log(chalk_1.default.cyan('\n\u2728 Project initialized with Pathmode intent context!'));
         console.log(chalk_1.default.gray('Run `pathmode pull` to update these files later.'));
@@ -11370,7 +11375,7 @@ program
     .command('pull')
     .description('Pull latest intent data from Pathmode and update local files')
     .option('--intent <id>', 'Specific intent ID to pull')
-    .option('--only <files>', 'Only update specific files (claude-md,cursorrules,intent-md)', '')
+    .option('--only <files>', 'Only update specific files (claude-md,agents-md,cursorrules,intent-md)', '')
     .action(async (options) => {
     console.log(chalk_1.default.cyan('\n\u2b07\ufe0f  Pathmode Pull\n'));
     const config = (0, api_client_1.loadConfig)();
@@ -11387,9 +11392,20 @@ program
             console.log(chalk_1.default.gray('Pulling CLAUDE.md content...'));
             const claudeMd = await client.exportClaudeMd();
             const claudePath = path_1.default.join(cwd, 'CLAUDE.md');
-            writeClaudeMdSection(claudePath, claudeMd);
+            writePathmodeSection(claudePath, claudeMd);
             console.log(chalk_1.default.green(`\u2705 Updated: CLAUDE.md`));
         }
+        // AGENTS.md is opt-in (Codex / modern Cursor). It carries the same
+        // agent-agnostic context as CLAUDE.md, so syncing it by default would
+        // just duplicate CLAUDE.md \u2014 only write it when explicitly requested
+        // via --only agents-md.
+        if (onlyFiles.includes('agents-md')) {
+            console.log(chalk_1.default.gray('Pulling AGENTS.md content...'));
+            const agentsMd = await client.exportAgentsMd();
+            const agentsPath = path_1.default.join(cwd, 'AGENTS.md');
+            writePathmodeSection(agentsPath, agentsMd);
+            console.log(chalk_1.default.green(`\u2705 Updated: AGENTS.md`));
+        }
         if (shouldUpdate('cursorrules')) {
             console.log(chalk_1.default.gray('Pulling .cursorrules...'));
             const cursorRules = await client.exportCursorRules(options.intent);
@@ -11511,10 +11527,10 @@ program
 const PATHMODE_START = '<!-- PATHMODE:START - Do not edit this section manually -->';
 const PATHMODE_END = '<!-- PATHMODE:END -->';
 /**
- * Write Pathmode section into CLAUDE.md, preserving any existing content
- * outside the PATHMODE:START/END markers.
+ * Write the Pathmode section into a CLAUDE.md / AGENTS.md style file,
+ * preserving any existing content outside the PATHMODE:START/END markers.
  */
-function writeClaudeMdSection(filePath, pathmodeContent) {
+function writePathmodeSection(filePath, pathmodeContent) {
     if (fs_1.default.existsSync(filePath)) {
         const existing = fs_1.default.readFileSync(filePath, 'utf-8');
         const startIdx = existing.indexOf(PATHMODE_START);

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@pathmode/cli",
-  "version": "2.0.0",
+  "version": "2.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "The Intent Layer CLI — Spec-Driven Development with Pathmode",
   "main": "dist/index.js",
   "bin": {