@outcomeeng/spx 0.1.8 → 0.3.0

package/README.md

@@ -4,14 +4,16 @@ Developer CLI for code validation and session management.
 
 ## What is spx?
 
-**spx** is a developer CLI that provides code validation and session management for spec-driven projects. It orchestrates linting, type checking, circular dependency detection, and manages work handoffs between agent contexts.
+`spx` is a command-line interface (CLI) tool that provides code validation and session management for projects that implement the spec-as-source methodology named [Outcome Engineering](https://outcome.engineering). The `spx` CLI works hand-in-hand with the **Claude Code** and **Codex** [plugin marketplace for Outcome Engineering](https://github.com/outcomeeng/plugins).
+
+The `spx` CLI orchestrates linting, type checking, circular dependency detection, markdown validation, literal reuse checks, and work handoffs between agent contexts.
 
 ### Key Benefits
 
-- **Unified validation**: Run ESLint, TypeScript, and circular dependency checks through a single command
-- **Session management**: Queue, claim, and hand off work between agents
-- **Multiple formats**: Text, JSON output for CI and automation
-- **Secure publishing**: OIDC Trusted Publishing with Sigstore provenance via GitHub Actions
+- Run the full quality gate through a single `spx validation all` command
+- Queue, claim, and hand off work between agents with `spx session`
+- Text and JSON output for CI and automation
+- OIDC Trusted Publishing with Sigstore provenance via GitHub Actions
 
 All commands are domain-scoped (e.g., `spx validation`, `spx session`) and support `--quiet` and `--json` flags for CI and automation.
 
@@ -35,18 +37,22 @@ pnpm link --global
 ### Code Validation
 
 ```bash
-# Full validation pipeline (circular deps → ESLint → TypeScript)
+# Full validation pipeline
 spx validation all
 
 # Individual checks
-spx validation lint           # ESLint
-spx validation lint --fix     # ESLint with auto-fix
-spx validation typescript     # TypeScript type checking
-spx validation circular       # Circular dependency detection
-spx validation knip           # Unused code detection
-
-# Production scope only (excludes tests/scripts)
-spx validation all --scope production
+spx validation lint              # ESLint
+spx validation lint --fix        # ESLint with auto-fix
+spx validation typescript        # TypeScript type checking (alias: spx validation ts)
+spx validation circular          # Circular dependency detection
+spx validation knip              # Unused code detection
+spx validation markdown          # Markdown link validation (alias: spx validation md)
+spx validation literal           # Source/test literal reuse detection
+
+# Scope and targeting
+spx validation all --scope production        # Exclude tests/scripts
+spx validation all --fix                     # Auto-fix across all checks
+spx validation all --files src/session/      # Validate specific files or directories
 ```
 
 All validation commands support `--quiet` for CI and `--json` for machine-readable output.
@@ -67,15 +73,24 @@ EOF
 # List all sessions
 spx session list
 
+# List todo sessions only
+spx session todo
+
 # Claim the highest priority session
 spx session pickup --auto
 
-# Release session back to queue
-spx session release
+# Release one or more sessions back to the todo queue
+spx session release [id...]
+
+# Archive a session
+spx session archive <session-id>
 
 # Show session content
 spx session show <session-id>
 
+# Remove old todo sessions (keeps 5 by default)
+spx session prune [--keep <n>] [--dry-run]
+
 # Delete a session
 spx session delete <session-id>
 ```
@@ -86,7 +101,7 @@ See [Session Recipes](docs/how-to/session/common-tasks.md) for detailed usage pa
 
 ### Spec Management (deprecated)
 
-The `spx spec` and `spx spx` CLI domains are **deprecated**. Spec tree management has moved to the **spec-tree** Claude Code plugin, available at [`outcomeeng/claude/plugins/spec-tree`](https://github.com/outcomeeng/claude). The plugin provides skills for understanding, authoring, decomposing, contextualizing, testing, refactoring, and aligning specification trees.
+The `spx spec` and `spx spx` CLI domains are **deprecated**. Spec tree management has moved to the **spec-tree** Claude Code plugin, available at [`outcomeeng/plugins`](https://github.com/outcomeeng/plugins). The plugin provides skills for understanding, authoring, decomposing, contextualizing, testing, refactoring, and aligning specification trees.
 
 ## Development
 
@@ -105,50 +120,61 @@ pnpm link --global  # Optional: makes 'spx' available in your shell
 ```bash
 pnpm run build          # Build with tsup
 pnpm run dev            # Build in watch mode
-pnpm test               # Run all tests
+pnpm test               # Build, then run all tests
 pnpm run test:watch     # Run tests in watch mode
 pnpm run test:unit      # Unit tests only
-pnpm run test:e2e       # End-to-end tests only
+pnpm run test:e2e       # Build, then run end-to-end tests
 pnpm run test:coverage  # Tests with coverage
 ```
 
 ### Validation (Required Before Commits)
 
 ```bash
-pnpm run validate       # Full pipeline: circular deps → ESLint → TypeScript
-pnpm run lint           # ESLint only
-pnpm run lint:fix       # ESLint with auto-fix
-pnpm run typecheck      # TypeScript only
-pnpm run circular       # Circular dependency detection
-pnpm run knip           # Unused code detection
+pnpm run validate              # Source CLI: full validation pipeline
+pnpm run validate:production   # Source CLI: production scope only
+pnpm run lint                  # Source CLI: ESLint only
+pnpm run lint:fix              # Source CLI: ESLint with auto-fix
+pnpm run typecheck             # Source CLI: TypeScript only
+pnpm run circular              # Source CLI: circular dependency detection
+pnpm run knip                  # Source CLI: unused code detection
+```
+
+The development validation scripts run `tsx src/cli.ts`, so they validate the current source tree. The packaged executable at `bin/spx.js` requires `dist/cli.js`; run `pnpm run build` before invoking it directly or through a global link.
+
+### Publish Validation
+
+```bash
+pnpm run publish:check        # Source validation, build, tests, packaged validation
+pnpm run validate:published   # Packaged executable validation; requires dist/cli.js
 ```
 
-The `pnpm run` scripts use `node bin/spx.js` internally, so they work without a global link. Once linked, you can also use `spx validation all` etc. directly.
+`pnpm run publish:check` is the required pre-publish gate. It runs source validation, builds `dist/`, runs the test suite, and then runs `node bin/spx.js validation all --scope production` against the built executable.
 
 ## CI/CD
 
 The project uses GitHub Actions for continuous integration and publishing:
 
-- **CI** (`ci.yml`) — Runs validate, test, and build on Node 22 and 24 for every push to `main` and every pull request. Includes dependency review to block PRs introducing vulnerable dependencies.
-- **Publish** (`publish.yml`) — Triggered by `v*` tags. Uses OIDC Trusted Publishing (no stored npm tokens) with Sigstore provenance attestation. Requires manual approval via the `npm-publish` GitHub Environment.
-- **Scorecard** (`scorecard.yml`) — Weekly OpenSSF Scorecard assessment, results published to the GitHub Security tab.
+- `ci.yml` — Runs validate, test, and build on Node 22 and 24 for every push to `main` and every pull request. Includes dependency review to block PRs introducing vulnerable dependencies.
+- `publish.yml` — Triggered by `v*` tags. Uses OIDC Trusted Publishing (no stored npm tokens) with Sigstore provenance attestation. Requires manual approval via the `npm-publish` GitHub Environment.
+- `scorecard.yml` — Weekly OpenSSF Scorecard assessment, results published to the GitHub Security tab.
 
 ### Publishing a Release
 
-1. Bump the version in `package.json`
-2. Commit and tag: `git tag vX.Y.Z`
-3. Push: `git push origin main && git push origin vX.Y.Z`
-4. Approve the deployment in the GitHub Actions `npm-publish` environment
-5. The package is published with provenance — verify with `npm audit signatures`
+1. Run `pnpm run publish:check`
+2. Bump the version in `package.json`
+3. Commit and tag: `git tag vX.Y.Z`
+4. Push: `git push origin main && git push origin vX.Y.Z`
+5. Approve the deployment in the GitHub Actions `npm-publish` environment
+6. Verify provenance with `npm audit signatures`
 
 ## Technical Stack
 
-- **TypeScript** — Type-safe implementation (ESM)
-- **Commander.js** — CLI framework
-- **Vitest** — Testing framework
-- **tsup** — Build tool (esbuild-based)
-- **ESLint 9** — Linting with flat config
-- **GitHub Actions** — CI/CD with OIDC Trusted Publishing
+- TypeScript — type-safe implementation (ESM)
+- Commander.js — CLI framework
+- Vitest — testing framework
+- tsup — build tool (esbuild-based)
+- ESLint 9 — linting with flat config
+- GitHub Actions — CI/CD with OIDC Trusted Publishing
 
 ## Architecture
 
@@ -156,7 +182,8 @@ The project uses GitHub Actions for continuous integration and publishing:
 src/
 ├── commands/      # CLI command implementations
 │   ├── session/     # spx session subcommands
-│   └── validation/  # spx validation subcommands
+│   ├── validation/  # spx validation subcommands
+│   └── spec/        # spx spec subcommands (deprecated)
 ├── domains/       # Domain routers
 ├── validation/    # Lint, typecheck, circular dep logic
 ├── session/       # Session lifecycle and storage

package/bin/spx.js

@@ -1,30 +1,27 @@
 #!/usr/bin/env node
 
 // CLI entry point
-// Use tsx for development when dist/cli.js doesn't exist
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const BUILD_COMMAND = "pnpm run build";
+const BUILT_CLI_FILENAME = "cli.js";
+const DIST_DIRECTORY = "dist";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const distPath = join(__dirname, "../dist/cli.js");
+const distPath = join(__dirname, "..", DIST_DIRECTORY, BUILT_CLI_FILENAME);
+
+if (!existsSync(distPath)) {
+  console.error(`Built CLI not found at ${distPath}`);
+  console.error(`Run "${BUILD_COMMAND}" before invoking the packaged spx executable.`);
+  process.exit(1);
+}
 
-if (existsSync(distPath)) {
-  try {
-    await import("../dist/cli.js");
-  } catch (err) {
-    console.error("Failed to load CLI:", err);
-    process.exit(1);
-  }
-} else {
-  // Development mode: use tsx to run source directly
-  try {
-    await import("tsx/esm");
-    await import("../src/cli.ts");
-  } catch (err) {
-    console.error("tsx not available and dist/cli.js not found:", err);
-    console.error("Run \"pnpm run build\" to build the CLI");
-    process.exit(1);
-  }
+try {
+  await import(pathToFileURL(distPath).href);
+} catch (err) {
+  console.error("Failed to load built CLI:", err);
+  process.exit(1);
 }