ultracode-for-codex 0.2.0

package/README.md

@@ -0,0 +1,182 @@
+# Ultracode for Codex
+
+Ultracode for Codex runs local workflows as CLI commands backed by an
+already-authenticated Codex CLI session. Progress streams to stderr as JSONL by
+default, the final result prints to stdout as JSON, and cancellation/retry stay
+inside the same command process.
+The packaged `settings.json` defaults workflow runs to OS background execution
+with result and progress files under `.ultracode-for-codex/background/{jobId}`.
+
+## Quick Start
+
+Install from npm:
+
+```bash
+npm install --save-dev ultracode-for-codex
+npm exec -- ultracode-for-codex --llm-guide
+```
+
+Build and verify a local installable tarball from a source checkout:
+
+```bash
+npm install
+npm run pack:ultracode-for-codex
+```
+
+Install the tarball from a target project:
+
+```bash
+npm install --save-dev /path/to/ultracode-for-codex-0.2.0.tgz
+```
+
+Run a workflow:
+
+```bash
+npm exec -- ultracode-for-codex run \
+  --accept-llm-guide=v1 \
+  --cwd /path/to/target-repo \
+  --script-file .codex/workflows/review.js \
+  --args '{"prompt":"review the current change"}'
+```
+
+By default this prints a background launch record to stdout. The record contains
+`jobId`, `pid`, `resultPath`, `progressPath`, `metadataPath`, and `pidPath`.
+
+Run attached to the current terminal:
+
+```bash
+npm exec -- ultracode-for-codex run \
+  --accept-llm-guide=v1 \
+  --execution attached \
+  --cwd /path/to/target-repo \
+  --script-file .codex/workflows/review.js \
+  --args '{"prompt":"review the current change"}'
+```
+
+Named workflows are resolved from `.codex/workflows`, user workflow folders,
+plugin workflow folders, and built-ins:
+
+```bash
+npm exec -- ultracode-for-codex run \
+  --accept-llm-guide=v1 \
+  --cwd /path/to/target-repo \
+  --name code-review \
+  --args '{"prompt":"review correctness risks"}'
+```
+
+## Settings
+
+Package defaults live in `settings.json`:
+
+```json
+{
+  "workflow": {
+    "executionMode": "background",
+    "progress": "jsonl",
+    "permission": "ask",
+    "retryLimit": 0,
+    "timeoutMs": 180000,
+    "background": {
+      "runDir": ".ultracode-for-codex/background/{jobId}",
+      "resultFile": "result.json",
+      "progressFile": "progress.jsonl",
+      "metadataFile": "metadata.json",
+      "pidFile": "pid"
+    }
+  }
+}
+```
+
+Use `--execution attached`, `--progress`, `--permission`, `--retry-limit`, and
+`--timeout-ms` to override settings for one run.
+
+## CLI Controls
+
+- Progress is printed to stderr as JSONL by default.
+- The final workflow result is printed as JSON to stdout.
+- JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
+  agent records also include stable agent identity and label fields.
+- Press `Ctrl-C` once to cancel the active workflow.
+- Use `--retry-limit <n>` to retry failed workflows inside the same process.
+- Use `--permission ask|allow|deny` for project/user/plugin/scriptPath workflow
+  permission reviews.
+- Use `--progress plain` for human-readable log lines.
+- Use `--execution background` for OS background runs and `--execution attached`
+  when Codex should read progress until completion.
+
+## Codex Companion Skill
+
+The npm package is the runtime artifact. The companion Codex skill in
+`skills/ultracode-for-codex` is a lightweight operating guide for agents using
+the package; it contains no runtime code.
+
+Install or copy that folder into `${CODEX_HOME:-$HOME/.codex}/skills` when you
+want Codex to auto-load the package boundaries and verification routine.
+
+## Runtime Boundaries
+
+- The only production backend is Codex app-server over stdio.
+- Direct provider credentials are stripped from the Codex child process
+  environment.
+- Workflow execution is local and command-owned; settings default to OS
+  background execution and `--execution attached` keeps the process connected
+  until completion.
+- `.ultracode-for-codex` workflow state is sensitive local data.
+- `journalPath`, `journal.jsonl`, and journal contents stay out of CLI output.
+  Local runtime state may still contain runtime-owned
+  `transcriptDir`, `scriptPath`, and result files.
+- `resumeFromRunId` remains runtime-internal and same-session; users retry the
+  active run or rerun the workflow command.
+- `agent(..., { isolation: "worktree" })` runs the agent in a detached git
+  worktree, removes it when clean, and preserves changed or unsafe-to-clean
+  worktrees for review.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run pack:ultracode-for-codex
+npm run test:e2e:ultracode-for-codex
+npm run test:all
+```
+
+## Publishing
+
+The npm package name is `ultracode-for-codex`. Public publish metadata lives in
+`package.json`, and `prepublishOnly` runs the full verification suite before
+`npm publish`.
+
+Check the package before publishing:
+
+```bash
+npm run publish:dry-run
+```
+
+Publish after `npm login`:
+
+```bash
+npm run publish:npm
+```
+
+For supported CI/CD environments, provenance is available as an explicit opt-in:
+
+```bash
+npm run publish:npm:provenance
+```
+
+Useful local run:
+
+```bash
+npm run build
+node dist/cli.js run --accept-llm-guide=v1 --script-file ./workflow.js
+```
+
+## Docs
+
+- `skills/ultracode-for-codex/SKILL.md`: Codex companion skill for operating
+  the npm runtime safely.
+- `ULTRACODE_INSTALL.md`: install and operating guide for LLM agents.
+- `docs/ultracode-p3a-journal-design.md`: journal contract.
+- `docs/ultracode-p3b-resume-cache.md`: runtime-internal resume/cache contract.
+- `docs/ultracode-p3c-worktree-isolation.md`: worktree isolation contract.

package/ULTRACODE_INSTALL.md

@@ -0,0 +1,133 @@
+# Ultracode install and usage guide
+
+This file is for LLM agents installing or operating `ultracode-for-codex`.
+Read it before running workflows or generating integration code.
+
+## What This Package Does
+
+`ultracode-for-codex` provides a local command-owned workflow runtime backed by an
+already-authenticated Codex CLI session. The packaged `settings.json` defaults
+workflow runs to OS background execution with result and progress files under
+`.ultracode-for-codex/background/{jobId}`.
+
+Production surface:
+
+- `ultracode-for-codex run`
+
+Progress, cancellation, permission review, retry, and final result projection
+are handled inside the CLI process. Progress is JSONL on stderr by
+default so Codex can parse and summarize workflow state.
+
+## Install
+
+Use the npm package for consumer installs.
+
+```bash
+npm install --save-dev ultracode-for-codex
+npm exec -- ultracode-for-codex --help
+npm exec -- ultracode-for-codex --llm-guide
+```
+
+For source-checkout validation, install the generated tarball instead:
+
+```bash
+npm install --save-dev ./ultracode-for-codex-0.2.0.tgz
+```
+
+Optional Codex companion skill:
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R ./node_modules/ultracode-for-codex/skills/ultracode-for-codex \
+  "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+The skill is only an operating guide. The npm package remains the runtime
+artifact.
+
+## Run
+
+```bash
+npm exec -- ultracode-for-codex run \
+  --accept-llm-guide=v1 \
+  --cwd /path/to/project \
+  --script-file .codex/workflows/review.js \
+  --args '{"prompt":"review the current change"}'
+```
+
+The default run prints a background launch record to stdout. Use
+`--execution attached` when Codex should read progress until completion.
+
+Settings defaults:
+
+```json
+{
+  "workflow": {
+    "executionMode": "background",
+    "progress": "jsonl",
+    "permission": "ask",
+    "retryLimit": 0,
+    "timeoutMs": 180000,
+    "background": {
+      "runDir": ".ultracode-for-codex/background/{jobId}",
+      "resultFile": "result.json",
+      "progressFile": "progress.jsonl",
+      "metadataFile": "metadata.json",
+      "pidFile": "pid"
+    }
+  }
+}
+```
+
+Useful controls:
+
+- Progress events are printed to stderr as JSONL by default.
+- The final workflow result is printed as JSON to stdout.
+- JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
+  agent records also include stable agent identity and label fields.
+- Press `Ctrl-C` once to cancel the running workflow.
+- Use `--retry-limit <n>` to retry failed runs in the same process.
+- Use `--permission ask|allow|deny` for project/user/plugin/scriptPath
+  workflow permission reviews.
+- Use `--progress plain` for human-readable log lines.
+- Use `--execution background` for OS background runs and `--execution attached`
+  for current-terminal progress streaming.
+
+## Runtime Contract
+
+- Use Codex app-server over stdio as the production backend.
+- Keep workflow execution local and command-owned; settings default to OS
+  background execution and `--execution attached` keeps the process connected
+  until completion.
+- Route progress, cancellation, permission review, retry, and result projection
+  through the CLI command.
+- Keep stdout reserved for the final JSON result; stream progress records to
+  stderr as JSONL unless a human chooses `--progress plain`.
+- Strip direct provider credentials from child CLI environments.
+- Install consumers from a packaged artifact.
+- Keep `journalPath`, `journal.jsonl`, and journal contents out of CLI output.
+  Local runtime state may still contain runtime-owned
+  `transcriptDir`, `scriptPath`, and result files.
+- `resumeFromRunId` remains a runtime-internal same-session capability; the
+  CLI uses retry or explicit reruns for user-facing recovery.
+- Use `isolation: "worktree"` only in git repositories with at least one commit.
+  Changed or unsafe-to-clean worktrees are intentionally preserved for review.
+- Treat `.ultracode-for-codex` workflow state as sensitive local data.
+
+## First Checks After Install
+
+```bash
+npm exec -- ultracode-for-codex --help
+npm exec -- ultracode-for-codex --llm-guide
+```
+
+If this guide is missing, treat the package as invalid. If `run` is used without
+`--accept-llm-guide=v1`, the CLI prints this guide and exits before executing a
+workflow.
+
+## Documentation Map
+
+- `README.md`: human quickstart and common examples.
+- `docs/ultracode-p3a-journal-design.md`: implemented journal contract.
+- `docs/ultracode-p3b-resume-cache.md`: runtime-internal resume/cache contract.
+- `docs/ultracode-p3c-worktree-isolation.md`: worktree isolation contract.

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+export type { WorkflowAgentPreservedWorktree, WorkflowEvent, WorkflowLaunchInput, WorkflowLaunchResult, WorkflowPermissionReview, WorkflowTaskSnapshot, WorkflowTaskStatus, WorkflowTaskType, } from './runtime/workflow-runtime.js';
+interface ParsedOptions {
+    readonly _: string[];
+    readonly args?: string;
+    readonly argsFile?: string;
+    readonly command?: string;
+    readonly model?: string;
+    readonly timeoutMs?: string;
+    readonly cwd?: string;
+    readonly execution?: string;
+    readonly reasoningEffort?: string;
+    readonly verbosity?: string;
+    readonly progress?: string;
+    readonly acceptLlmGuide?: string;
+    readonly script?: string;
+    readonly scriptFile?: string;
+    readonly scriptPath?: string;
+    readonly name?: string;
+    readonly resumeFromRunId?: string;
+    readonly permission?: string;
+    readonly retryLimit?: string;
+}
+export declare function parseOptions(args: readonly string[]): ParsedOptions;