mimetic-cli 0.1.2 → 0.1.4

package/docs/architecture/observer.md

@@ -0,0 +1,109 @@
+# Observer Architecture
+
+Date: 2026-06-01
+
+Status: implemented for synthetic stream contracts and local `codex-exec`
+active-run Observer snapshots; broader live actor adapters next.
+
+## Decision
+
+The Observer is a mission-control surface over durable run artifacts, not a
+static report page.
+
+Every run writes immutable local evidence under `.mimetic/runs/<run-id>/`:
+
+```text
+.mimetic/runs/<run-id>/
+  run.json
+  review.json
+  review.md
+  events.ndjson
+  observer/
+    index.html
+    observer-data.json
+```
+
+`run.json` remains the source bundle. `observer/observer-data.json` is the
+normalized view model consumed by the Observer. `events.ndjson` is the appendable
+event stream contract that live adapters will update while a run is active.
+
+## Stream Model
+
+Streams are the central abstraction. A stream is one watchable persona lane,
+regardless of substrate:
+
+- `ui`: browser/VNC style UI simulation lane;
+- `browser`: browser-specific lane when the app and actor are separate;
+- `terminal`: CLI persona lane with stdout/stderr evidence;
+- `tui`: PTY/ANSI terminal UI lane;
+- `codex-ui`: Codex-style app-server session lane;
+- `artifact`: artifact-only evidence lane;
+- `summary`: run-level synthesis lane.
+
+Each stream points back to a simulation and carries its own transport,
+terminal tail, UI state, artifact links, event timeline, and public-safe
+metadata.
+
+## Live Watch
+
+`mimetic watch` now:
+
+1. creates a fresh four-lane synthetic run bundle;
+2. writes `observer-data.json` and `events.ndjson`;
+3. starts a localhost Observer server;
+4. opens the served Observer URL;
+5. keeps the shell attached until Ctrl-C.
+
+The browser polls `observer-data.json` with `no-store` caching. Static
+`file://` opening still works for immutable review, but follow mode is the
+operator path. Agents and CI should use `mimetic watch --json --no-open` for
+the same fresh evidence without browser open or a long-running process.
+
+Local `codex-exec` actor runs now publish an initial running `run.json` and
+`observer/observer-data.json` before actor completion, then refresh both after
+sanitized transcripts, traces, and verdict events are available. This gives a
+served Observer a truthful active state to poll while noninteractive local
+actors are still running.
+
+## UI Shape
+
+The Observer shell has:
+
+- top mission-control band with run status and metrics;
+- stream filters for UI, CLI, TUI, and Codex UI lanes;
+- grid mode with one tile per sim stream;
+- focus mode with left stream rail, center stage, and right tabs;
+- terminal/TUI transcript stage;
+- right evidence rail for events, artifacts, and known gaps.
+
+## Codex UI Contract
+
+`codex-ui` streams are normalized session/event projections. Public artifacts
+must not store raw provider payloads, raw prompts, raw private transcripts,
+private screenshots, PHI, PII, secrets, or upstream data.
+
+A host adapter may provide:
+
+- session identity;
+- redacted lifecycle/status;
+- event source or snapshot URL;
+- optional embed URL;
+- normalized event timeline;
+- approval metadata;
+- public-safe artifact links.
+
+If no embed URL exists, the Observer still renders the Codex-style timeline and
+session contract instead of failing the lane.
+
+## Current Gaps
+
+This slice implements the Observer substrate, synthetic stream contracts, and
+active-run Observer snapshots for local `codex-exec`. The following are
+intentionally still adapter work:
+
+- real Playwright/browser actor execution;
+- E2B or local PTY capture;
+- Codex TUI live follow after workspace trust bootstrap;
+- native Codex app-server session adapter;
+- screenshot and trace galleries;
+- reviewer acceptance gates over real product behavior.

package/docs/architecture/oss-lab-poc.md

@@ -0,0 +1,170 @@
+# OSS Lab POC
+
+Date: 2026-06-01
+
+Status: implemented as an experimental meta-lab command plus a retained smoke
+harness.
+
+## Decision
+
+`mimetic lab oss` is the public-OSS meta-simulation loop.
+
+The command should feel like `mimetic watch`: it opens the Observer and, for
+human output, keeps the shell attached. Its top-level Observer is an
+Observer-of-Observers: each lane represents a headed E2B desktop that will run
+Codex TUI against a different lightweight public GitHub repository. Inside each
+desktop, Codex should clone the repo, get it into local dev mode where feasible,
+install and initialize Mimetic, author plausible public-safe personas/scenarios,
+run nested Mimetic proof commands, attempt a Codex TUI pass, and leave that
+nested Observer visible in the E2B browser.
+
+The previous clone/discard proof loop remains useful, but it is now explicitly
+named `mimetic lab oss-smoke`.
+
+## Commands
+
+Main operator path:
+
+```bash
+mimetic lab oss
+mimetic lab oss --repos developit/mitt,lukeed/clsx,sindresorhus/is-plain-obj,ai/nanoid
+mimetic lab oss --repo developit/mitt --repo lukeed/clsx --count 4
+```
+
+Agent/CI contract path:
+
+```bash
+mimetic lab oss --dry-run --json --no-open
+```
+
+Disposable clone smoke path:
+
+```bash
+mimetic lab oss-smoke
+mimetic lab oss-smoke --limit 1 --keep
+mimetic lab oss --smoke --limit 1 --keep
+```
+
+Local dogfood shortcuts:
+
+```bash
+pnpm mimetic:lab:oss
+pnpm mimetic:lab:oss:ci
+pnpm mimetic:lab:oss:smoke
+```
+
+## Repo Selection
+
+The default public targets are intentionally small JavaScript packages:
+
+- `developit/mitt`
+- `lukeed/clsx`
+- `sindresorhus/is-plain-obj`
+- `ai/nanoid`
+
+`--repos` accepts a comma-separated list. Repeated `--repo` is also supported.
+If `--count` is larger than the repo list, assignments cycle through the repo
+pool. Inputs must be public GitHub `owner/repo` slugs. Arbitrary URLs, local
+paths, tokens, SSH remotes, and private GitHub references are rejected.
+
+## Runtime Shape
+
+The meta-lab writes ignored local Observer evidence:
+
+```text
+.mimetic/
+  runs/<oss-meta-run-id>/
+    run.json
+    review.json
+    review.md
+    events.ndjson
+    observer/
+      index.html
+      observer-data.json
+```
+
+Each stream lane records:
+
+- assigned repo slug;
+- live E2B desktop stream URL when keys are present;
+- Codex TUI bootstrap prompt;
+- current live-readiness state;
+- public-safe gaps and events.
+
+The current implementation launches live E2B desktop streams when
+`E2B_API_KEY` and `OPENAI_API_KEY` are present, embeds those streams into the
+top-level Observer, and marks missing key or launch failures in-lane. It also
+packs the local Mimetic package, uploads it into each sandbox, raises a visible
+bootstrap terminal, clones the assigned public repo, runs nested Mimetic setup
+and proof commands, attempts a Codex TUI pass, and opens the nested Observer in
+the sandbox browser.
+
+The live desktop substrate is an optional peer dependency. Install it in the
+project that runs live labs:
+
+```bash
+npm i -D @e2b/desktop
+```
+
+Remaining substrate work: poll remote bootstrap completion and nested Observer
+health back into the top-level bundle instead of leaving completion review to
+the live desktop stream.
+
+## Smoke Harness Runtime
+
+`mimetic lab oss-smoke` shallow clones lightweight public GitHub repos into
+ignored runtime state, applies Mimetic setup inside each throwaway clone, runs
+the synthetic four-lane proof path, verifies the generated bundle, records
+git-status evidence, writes an ignored report, and removes cloned repos by
+default.
+
+```text
+.mimetic/
+  lab/oss/<run-id>/
+    report.json
+    report.md
+  tmp/oss-lab/<run-id>/
+    repos...      # removed by default
+```
+
+Each cloned repo receives disposable uncommitted changes:
+
+- `mimetic/` source starter files;
+- `.mimetic/` runtime state;
+- `.gitignore` updates;
+- `package.json` script updates;
+- synthetic run/Observer evidence under the clone's ignored `.mimetic/`.
+
+The clone is removed unless `--keep` is passed. The host report remains under
+ignored `.mimetic/lab/oss/<run-id>/`.
+
+## Safety Rules
+
+- Public GitHub `owner/repo` slugs only.
+- No credential prompts; smoke clone calls set `GIT_TERMINAL_PROMPT=0`.
+- No commits, pushes, branches, tags, GitHub API mutation, deploys, or issue
+  filing.
+- Do not write key values into committed `mimetic/` source.
+- Do not emit PII, PHI, raw private transcripts, private screenshots, secrets,
+  keys, or private upstream artifacts.
+
+## What This Proves
+
+The meta-lab proves the operator control surface and artifact contract for
+watching multiple Codex/E2B OSS setup attempts at once. The live path now proves
+E2B desktop fanout, visible bootstrap terminals, local-package upload, disposable
+public-repo setup, nested Mimetic proof generation, and nested Observer opening.
+It does not yet prove remote completion polling or a general provider-backed
+target-app persona runtime.
+
+The smoke harness proves first-run Mimetic package compatibility against
+arbitrary public JavaScript repositories:
+
+- setup can patch real package.json files without committing;
+- generated `mimetic/` source can coexist with external repo layout;
+- ignored `.mimetic/` runtime proof can be generated;
+- the Observer can render from those disposable proofs;
+- verification passes before the clone is discarded.
+
+Neither path may claim private product behavior proof without live, redacted,
+public-safe evidence.

package/docs/architecture/project-layout.md

@@ -0,0 +1,132 @@
+# Project Layout Contract
+
+Date: 2026-06-01
+
+Status: target layout for apps that install `mimetic-cli`.
+
+## Decision
+
+Use two roots:
+
+```text
+mimetic/   # committed source of simulation intent
+.mimetic/  # ignored runtime state, evidence, local overlays, and secrets
+```
+
+Do not gitignore all Mimetic state. Personas, scenarios, policies, adapters,
+coverage maps, and review vocabulary are the harness. They must be versioned,
+reviewed, and reproducible from a clean clone.
+
+Do not commit run bundles, raw screenshots, browser traces, transcripts,
+draft issue bodies before verification, local auth, local overrides, or secrets.
+
+## Committed Source Plane
+
+`mimetic/` is the project-owned simulation contract:
+
+```text
+mimetic/
+  README.md
+  config.ts
+  personas/
+    synthetic-new-user.yaml
+    skeptical-power-user.yaml
+  scenarios/
+    first-run-smoke.yaml
+    onboarding-regression.yaml
+  policies/
+    redaction.yaml
+    network.yaml
+    credentials.example.yaml
+  adapters/
+    app.ts
+  review/
+    vocabulary.yaml
+    milestones.yaml
+  coverage-map.md
+  coverage-matrix.md
+  fixtures/
+    synthetic-login-state.json
+```
+
+Committed files must be public-safe:
+
+- synthetic personas only;
+- synthetic or redacted fixtures only;
+- env var names only, never values;
+- no PHI, PII, keys, tokens, raw private transcripts, real screenshots, real
+  customer data, or real patient data.
+
+Changing a scenario or persona is equivalent to changing a test. It should be
+visible in PR review.
+
+## Ignored Runtime Plane
+
+`.mimetic/` is local/generated state:
+
+```text
+.mimetic/
+  runs/
+    <run-id>/
+      run.json
+      review.md
+      review.json
+      observer/
+      screenshots/
+      traces/
+      terminal/
+      feedback/
+  cache/
+  tmp/
+  logs/
+  local/
+  secrets/
+```
+
+Default `.gitignore` entry:
+
+```gitignore
+.mimetic/
+.env*
+```
+
+If a target repo already uses `.env.example`, preserve its existing exception.
+
+## Local Overrides
+
+When a team needs private local personas or credentials, use ignored overlays:
+
+```text
+.mimetic/local/personas/*.yaml
+.mimetic/local/policies/*.yaml
+.mimetic/secrets/*
+```
+
+The CLI should warn that local overlays cannot be used for reproducible CI or
+public issue drafts unless redacted into committed synthetic equivalents.
+
+## CI And Reproducibility
+
+CI should reproduce proof from committed inputs:
+
+- app commit;
+- `mimetic-cli` version;
+- `mimetic/config.ts`;
+- scenario and persona catalog;
+- policy files;
+- synthetic fixtures;
+- declared env var names.
+
+CI should store generated run bundles as artifacts, not commit them.
+
+## Why Not `.mimetic/` For Everything?
+
+A fully ignored `.mimetic/` makes setup feel tidy, but it hides the product
+contract. Future agents and contributors cannot see what the harness is meant
+to prove, CI cannot validate it from a clean clone, and PR review cannot catch
+weakened personas or dropped hard paths.
+
+A partially tracked dotdir is possible but worse UX. Dotdirs read as local,
+editors hide them, and negated gitignore rules are easy to break. A visible
+`mimetic/` source root plus ignored `.mimetic/` runtime root is clearer.
+

package/docs/contracts/adapter-fixtures.md

@@ -0,0 +1,80 @@
+# Adapter Fixture Parity Contract
+
+Date: 2026-06-02
+
+Status: v0 draft contract for public-safe adapter fixture parity.
+
+## Purpose
+
+Adapter fixtures prove that Mimetic can carry target-specific evidence without
+moving target truth into core schemas. A fixture is not a product claim. It is a
+public-safe contract packet that shows the routes, personas, milestones,
+terminal evidence, feedback drafts, and policy decisions a real adapter must
+emit before live behavior can be trusted.
+
+The fixture contract keeps three boundaries explicit:
+
+- Core owns run-bundle identity, artifact layout, verification, review,
+  redaction, and feedback mechanics.
+- Adapters own target routes, scenario language, personas, milestone names,
+  command surfaces, and acceptance proof.
+- Public issue drafts use redacted artifact pointers only; they do not require
+  GitHub tokens, hosted product memory, private transcripts, or live mutation.
+
+## Fixture Set
+
+The committed fixture set lives under `adapters/fixtures/`.
+
+| Fixture | Proves | Required artifacts |
+| --- | --- | --- |
+| `post-auth-return-dry-run` | A web-app adapter can keep upload, studio, and auth-return milestones adapter-owned while emitting a product-neutral dry-run bundle. | `adapter.json`, `persona.json`, `scenario.json`, `milestones.json`, `run-bundle.json` |
+| `terminal-feedback-lifecycle` | A terminal-first adapter can emit sanitized transcript evidence, issue-draft material, cost/redaction policy, verification checks, and feedback lifecycle proof without browser-only assumptions. | `adapter.json`, `policy.json`, `run-bundle.json`, `feedback-draft.json`, `verify-result.json`, `transcripts/sanitized-terminal.txt` |
+
+## Promotion Gates
+
+A fixture can be promoted only when:
+
+- every example is synthetic or redacted;
+- artifact paths are relative and do not contain traversal segments, absolute
+  local paths, hosted stream URLs, or auth-bearing links;
+- credential policy records env var names only, never values;
+- adapter-owned nouns do not appear in core schema docs or core runtime code;
+- public feedback material states that GitHub mutation was not performed;
+- the fixture can be checked with `pnpm test tests/adapter-fixtures.test.ts`
+  and `pnpm public-surface:scan`.
+
+## Dry-Run Web-App Fixture Shape
+
+The web-app fixture models a local app with three adapter-owned route groups:
+
+- `upload`: synthetic file input and validation state;
+- `studio`: synthetic work surface and result-review state;
+- `auth-return`: a post-authentication return path using a synthetic state id.
+
+The dry-run bundle does not add route or milestone fields to core. Instead, it
+references adapter-owned routes through `streams[].ui.route`, milestone events
+through lifecycle/event records, and the milestone manifest through relative
+artifact pointers.
+
+## Terminal Feedback Fixture Shape
+
+The terminal fixture models a command-driven product surface. Its bundle uses a
+`terminal` evidence stream, a sanitized transcript pointer, a feedback
+candidate, a separate feedback draft artifact, and a verification result that
+checks required public-safe files without reading or requiring raw private
+transcripts. Policy is adapter-owned and records:
+
+- `spend_policy: no_spend`;
+- `network_policy: no_network`;
+- `github.mutation: not_requested`;
+- `hosted_product_memory.required: false`;
+- redaction status and denied material classes.
+
+This keeps terminal and feedback parity independent from browser screenshots.
+
+## Proof Commands
+
+```bash
+pnpm test tests/adapter-fixtures.test.ts
+pnpm public-surface:scan
+```

package/docs/contracts/core.md

@@ -0,0 +1,71 @@
+# Core Contract
+
+Date: 2026-06-02
+
+Status: v0 draft contract with tested primitive helpers in `src/core`.
+
+## Purpose
+
+Core is the reusable layer that makes a run bundle stable enough for agents,
+reviewers, and maintainers to trust. It owns generic run identity, artifact
+layout, source state summaries, lifecycle records, latest/history pointers, and
+timing summaries.
+
+Core does not own product routes, personas, scenarios, app topology, provider
+setup, or repository-specific proof language.
+
+## Public-Safe Defaults
+
+Core records must be safe to include in public run bundles by default:
+
+- artifact paths are relative;
+- run ids contain only lowercase letters, numbers, and dashes;
+- git state summarizes status without branch names, remotes, file names, file
+  paths, or absolute working directories;
+- lifecycle and timing records are explicit inputs, not inferred prose;
+- latest/history pointers identify local artifacts, not hosted private logs.
+
+## Primitive Set
+
+| Primitive | Contract |
+| --- | --- |
+| Run id | Deterministic from explicit prefix, timestamp, and entropy; valid ids match `^[a-z0-9][a-z0-9-]{0,127}$`. |
+| Artifact layout | Builds stable relative pointers under `.mimetic/runs/<run-id>/` plus `.mimetic/runs/latest.json`. |
+| Latest pointer | `{ schema, runId, path, updatedAt }` using `mimetic.latest-run.v1`. |
+| History entry | `{ schema, runId, createdAt, mode, path }` using `mimetic.run-history-entry.v1`. |
+| Lifecycle event | `{ at, event, message }`; event and message are required. |
+| Timing summary | `{ startedAt, endedAt, durationMs, status }`; running records have null end and duration. |
+| Git state | `{ schema, status, capturedAt, head, changes, note }` using `mimetic.git-state.v1`. |
+
+## Git State Boundary
+
+Git state is intentionally lossy. It answers:
+
+- is this a work tree?
+- is it clean or dirty?
+- what short HEAD hash is available?
+- is HEAD attached, detached, unborn, or unknown?
+- how many staged, unstaged, and untracked entries exist?
+
+It does not record:
+
+- branch names;
+- remotes;
+- file names;
+- file paths;
+- absolute directories;
+- diffs;
+- commit messages.
+
+That makes it useful for repeatability and review without turning run bundles
+into a source leak.
+
+## Stop Conditions
+
+Core work stops if:
+
+- a core primitive needs a product-specific noun to make sense;
+- an artifact path can escape the run root;
+- a public record includes a raw cwd, branch name, remote, file name, diff, or
+  credential-like value;
+- a run id cannot be reproduced from explicit inputs.

package/docs/contracts/feedback.md

@@ -0,0 +1,131 @@
+# Feedback Contract
+
+Date: 2026-06-01
+
+Status: v0 dry-run contract implemented for local issue draft generation.
+
+## Purpose
+
+Feedback is the bridge between simulation evidence and public issue filing.
+
+`mimetic feedback` should let a persona simulation say:
+
+```text
+this user-like run found this concrete friction
+here is the evidence
+here is the likely owner
+here is the redaction proof
+here is the next state
+```
+
+It should not be an issue spammer, infra dependency, or generic comment
+collector.
+
+## Privacy Rule
+
+Feedback payloads must be public-safe by default. They may not contain PII,
+PHI, secrets, keys, tokens, raw private transcripts, private screenshots, raw
+customer data, raw patient data, or private product source.
+
+Public issue drafting fails closed if redaction cannot prove the payload is
+safe.
+
+## Command Stages
+
+```bash
+mimetic feedback list --run latest
+mimetic feedback draft --run latest --json
+mimetic feedback verify --run latest --json
+mimetic feedback issue --run latest --repo owner/repo --format markdown
+mimetic feedback issue-url --run latest --repo owner/repo
+```
+
+### `list`
+
+Reads feedback candidates from the run bundle. Does not mutate.
+
+### `draft`
+
+Builds structured feedback from review output and raw evidence pointers. Writes
+a draft under the run bundle, not GitHub.
+
+### `verify`
+
+Checks schema, evidence pointers, idempotency key, redaction result, and public
+issue eligibility.
+
+### `issue`
+
+Prints or writes a public-safe GitHub issue body. It does not call the GitHub
+API. The user files the issue in the public or eventually public repository.
+
+### `issue-url`
+
+Prints a prefilled GitHub issue URL when the platform supports one. It still
+does not create the issue.
+
+## Schema
+
+```yaml
+mimetic_feedback:
+  schema: mimetic.feedback.v1
+  run_id: "<run-id>"
+  adapter_id: "<adapter-id>"
+  scenario_id: "<scenario-id>"
+  persona_id: "<persona-id-or-class>"
+  actor: "<actor-runtime>"
+  substrate: "<substrate>"
+  failure_owner: "product_ux|agent_runtime|executor_substrate|payment_provider|model_provider|harness|unknown"
+  summary: "<public-safe concrete summary>"
+  expected: "<public-safe expected behavior>"
+  actual: "<public-safe observed behavior>"
+  source_bundle: "<path-or-url>"
+  evidence:
+    - path: "<relative artifact pointer>"
+      kind: "screenshot|terminal|browser|state|media|review|trace"
+      note: "<public-safe note>"
+  redaction:
+    status: "passed|failed|not_applicable"
+    notes: "<public-safe note>"
+  idempotency_key: "<stable-key>"
+  proposed_next_state: "watch|needs_spec|spec_ready|agent_ready|blocked|wontfix"
+  acceptance_proof:
+    - "<command or artifact that would close this>"
+```
+
+## Failure Owners
+
+| Owner | Meaning |
+| --- | --- |
+| `product_ux` | The product confused, blocked, or failed the user/persona. |
+| `agent_runtime` | The actor model/tool runtime failed independent of product UX. |
+| `executor_substrate` | E2B, local browser, shell, filesystem, or network substrate failed. |
+| `payment_provider` | Hosted payment/provider behavior blocked the run. |
+| `model_provider` | Model/media provider behavior blocked the run. |
+| `harness` | Mimetic or adapter logic produced invalid evidence or execution. |
+| `unknown` | Evidence is useful but ownership is not yet clear. |
+
+## Issue Draft Gates
+
+Generating a public issue draft is blocked when:
+
+- required schema fields are missing;
+- source bundle is missing;
+- evidence pointers are missing or invalid;
+- redaction did not pass;
+- any payload may contain PII, PHI, secrets, or private operational context;
+- proposed next state is `agent_ready` without a readiness block;
+- the feedback is a dry-run-only product claim;
+- idempotency key is missing.
+
+## GitHub Issue Semantics
+
+GitHub issues filed from feedback should say `contributes to` unless the
+acceptance proof closes the full product claim. The public issue should include
+only redacted evidence pointers and reproduction instructions that a maintainer
+can use without private local context.
+
+The public CLI should not require GitHub tokens, hosted product memory, queues,
+webhooks, Actions, databases, or Projects. Maintainers may later build separate
+repo-local tooling that consumes the same issue schema, but that is outside the
+default public feedback path.