mimetic-cli 0.1.2 → 0.1.4

package/docs/release/public-readiness-standard.md

@@ -0,0 +1,205 @@
+# Public Readiness Standard
+
+Status: researched working standard for public repository and npm release hygiene.
+
+This document separates real public-release risk from preference cleanup. The
+goal is to keep `mimetic-cli` safe, useful, and professional without deleting the
+durable context future contributors and agents need.
+
+## Sources Reviewed
+
+- [GitHub Docs: Removing sensitive data from a repository](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)
+- [GitHub Docs: Setting your commit email address](https://docs.github.com/en/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address)
+- [GitHub Docs: About secret scanning](https://docs.github.com/code-security/secret-scanning/about-secret-scanning)
+- [GitHub Docs: About push protection](https://docs.github.com/en/code-security/concepts/secret-security/about-push-protection)
+- [npm Docs: package.json files field](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/#files)
+- [npm Docs: npm publish package contents](https://docs.npmjs.com/cli/v9/commands/npm-publish#files-included-in-package)
+- [npm Docs: Trusted publishing for npm packages](https://docs.npmjs.com/trusted-publishers/)
+- [OpenSSF Scorecard](https://scorecard.dev/)
+- [OpenSSF Source Code Management Platform Configuration Best Practices](https://best.openssf.org/SCM-BestPractices/)
+- [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)
+
+## Decision Model
+
+Use four categories.
+
+### 1. Public Blockers
+
+These must be removed from the current tree, package payload, generated docs,
+screenshots, logs, and reachable history before the repo is public.
+
+- Secrets: API keys, provider tokens, npm/GitHub tokens, private keys, cookies,
+  session URLs, database URLs with credentials, `.env` values, auth-bearing
+  request headers, and raw credential material.
+- PHI, patient data, customer data, private user identifiers, private emails,
+  phone numbers, addresses, account IDs, billing IDs, raw transcripts, and raw
+  screenshots from private systems.
+- Private source snippets, internal-only product names, private roadmaps,
+  incident details, or operational data that would expose a non-public system or
+  customer relationship.
+- Built package output, source maps, docs, fixtures, or image assets that contain
+  any of the above.
+
+If a real secret was exposed, revoke or rotate it first. GitHub explicitly warns
+that history rewriting has side effects and may not be warranted once the secret
+is revoked. Rewrite history only when sensitive data remains materially risky
+after revocation, or when privacy, legal, contractual, or proprietary-source
+obligations require removal.
+
+### 2. Release-Gate Hygiene
+
+These should fail CI or release checks until fixed, but they are not all reasons
+to rewrite history.
+
+- Package payload is not inspected with `npm pack --dry-run`.
+- Scanner only checks tracked source and misses built `dist`, source maps, docs
+  packaged by `files`, or generated assets.
+- Binary public assets are not approved by path and checksum.
+- Docs link to files that are not shipped or not reachable from the public repo.
+- Runtime artifacts are included: `.mimetic/`, run bundles, transcripts,
+  disposable clones, `.firecrawl/`, `.e2b/`, logs, tarballs, caches.
+- GitHub Actions use broad default permissions where read-only is enough.
+- Publish workflow uses long-lived npm tokens when OIDC trusted publishing is
+  available.
+- Secret scanning, push protection, or equivalent local scanners are absent from
+  the operating checklist.
+
+### 3. Acceptable Public Metadata
+
+These are acceptable when intentional and public-safe. They should not trigger
+panic cleanup or history rewrite by default.
+
+- Maintainer name, GitHub username, public repo owner, public issue links, and
+  public repository URLs.
+- A maintainer-approved public commit email. GitHub allows either a noreply
+  address or any configured email for commits. Noreply is a privacy preference,
+  not a universal public-release requirement.
+- Env var names without values, such as `OPENAI_API_KEY` or `E2B_API_KEY`.
+- Synthetic personas, synthetic screenshots, synthetic app data, and redacted
+  proof examples.
+- Public-safe ramp, goal, architecture, and roadmap docs that help future
+  contributors continue the project.
+
+### 4. Professionalism Cleanup
+
+These do not usually justify history rewrite, but they matter for an open-source
+repo people will judge quickly.
+
+- Chat residue, private-process phrasing, or emotional notes that do not help a
+  public maintainer.
+- Overly specific local machine paths or private workspace names, even when not
+  security-sensitive.
+- Broken links, stale commands, claims of product proof where only contract proof
+  exists, and docs that depend on private chat memory.
+- Screenshots that are technically synthetic but look sloppy, confusing, or
+  embarrassing.
+
+Professionalism cleanup should preserve useful context. Deleting all ramp or
+goal docs is worse than rewriting them into a public-safe form.
+
+## Commit Email Policy
+
+Noreply commit emails are preferred for privacy and consistency.
+
+Allowed commit metadata:
+
+- GitHub noreply addresses.
+- `noreply@github.com` for GitHub-generated commits.
+- Explicitly approved public maintainer emails.
+
+Blocked commit metadata:
+
+- Unknown personal emails.
+- Contractor, employee, patient, customer, vendor, or private-domain emails that
+  are not intentionally public for this project.
+- Any email that appears in logs, transcripts, screenshots, or docs as private
+  user/customer data rather than maintainer metadata.
+
+Do not force-rewrite `main` solely because a known maintainer-approved public
+email appears in a commit. Document the approval and update the scanner
+allowlist instead.
+
+## NPM Package Surface
+
+The npm package is its own public surface. The release gate must inspect:
+
+- `npm pack --dry-run --json` output;
+- compiled `dist`;
+- source maps;
+- all files matched by `package.json.files`;
+- always-included files such as `package.json`, `README.md`, and `LICENSE`;
+- docs, skills, screenshots, and other assets shipped for npm-page display.
+
+The package should use the `files` field as an allowlist, but that is not enough.
+The scanner must union tracked source files with the actual npm dry-run payload.
+
+Public binary assets are allowed only when:
+
+- the asset is intentionally public;
+- the asset is synthetic or redacted;
+- the path is allowlisted;
+- the SHA-256 checksum is pinned in the scanner.
+
+## GitHub And Supply Chain Posture
+
+Minimum public-repo posture:
+
+- branch protection or rulesets for `main`;
+- required CI before merge;
+- workflow permissions narrowed to read-only unless a job needs more;
+- no long-lived npm token in Actions for publish;
+- npm trusted publishing via OIDC where possible;
+- secret scanning and push protection enabled where available;
+- `SECURITY.md`, `CONTRIBUTING.md`, `LICENSE`, and clear issue flow;
+- periodic OpenSSF Scorecard or equivalent review.
+
+Nice-to-have after public launch:
+
+- dependency update automation;
+- CodeQL or comparable SAST;
+- release provenance and staged publishing where practical;
+- signed releases when the release process matures.
+
+## Mimetic Application
+
+For `mimetic-cli`, the honest standard is:
+
+- Keep `docs/ramp/` and `docs/goals/` if they are public-safe. They are essential
+  project memory for future coding agents and contributors.
+- Keep the package docs and skill docs focused on public install, public-safe
+  examples, and synthetic proof.
+- Do not commit `.mimetic/`, `.firecrawl/`, screenshots from private systems,
+  raw run bundles, private transcripts, local env files, or packed tarballs.
+- Treat `dist` and source maps as public and scan them.
+- Treat the README screenshot as public and checksum-gated.
+- Allow a maintainer-approved public email in commit metadata; do not classify it
+  as a secret.
+- Rewrite history only for actual sensitive data, private source, or private
+  identity/customer data that remains materially risky.
+
+## Practical Checklist
+
+Before making the repository public or cutting a public package:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm release:check
+git diff --check
+npm pack --dry-run --json
+```
+
+Also verify in GitHub:
+
+- `main` branch protection/ruleset is active;
+- secret scanning and push protection are enabled where available;
+- publish workflow uses OIDC trusted publishing;
+- failed workflow logs do not contain real secrets or private data;
+- visible issues, PRs, labels, and project metadata do not expose private context.
+
+If a check fails, classify it before reacting:
+
+1. Secret/PHI/private source? Rotate/revoke first, then consider history rewrite.
+2. Package leak or private artifact? Remove from package/tree and rerun gates.
+3. Unknown private identity metadata? Approve, redact, or rewrite based on risk.
+4. Public maintainer metadata? Usually allowlist and document.
+5. Sloppy public docs? Rewrite, do not delete useful project memory.

package/docs/roadmap/world-class-open-source-v0.md

@@ -0,0 +1,286 @@
+# World-Class Open-Source V0 Roadmap
+
+Date: 2026-06-01
+
+Status: staged build plan for `mimetic-cli`.
+
+## Target Outcome
+
+A maintainer can install `mimetic-cli` into a normal JavaScript app, let their
+coding agent run setup, and get a public-safe persona simulation harness with:
+
+- committed `mimetic/` source plane;
+- ignored `.mimetic/` runtime plane;
+- `commander` CLI;
+- safe `init`;
+- synthetic dry-run bundle;
+- verifier;
+- observer;
+- public-safe feedback issue draft;
+- clear docs and agent skill.
+
+## Stage 0: Repo Plan And Issue Queue
+
+Status: complete enough to start implementation.
+
+Proof:
+
+- GitHub project `mimetic-cli`;
+- seeded issues;
+- future-public boundary docs;
+- feedback issue-draft doctrine.
+- layout/install/goal docs;
+- implementation tickets for the install path.
+
+Primary issue queue:
+
+- [#13 package: scaffold npm package and Commander mimetic binary](https://github.com/danielgwilson/mimetic-cli/issues/13)
+- [#14 init: scaffold committed mimetic source and ignored .mimetic runtime layout](https://github.com/danielgwilson/mimetic-cli/issues/14)
+- [#16 fixtures: create target app fixture for init, dry-run, verify, and observer proof](https://github.com/danielgwilson/mimetic-cli/issues/16)
+- [#7 cli: scaffold doctor, run --dry-run, review, verify, runs, and watch](https://github.com/danielgwilson/mimetic-cli/issues/7)
+- [#6 core: run IDs, artifact paths, git state, history, and lifecycle primitives](https://github.com/danielgwilson/mimetic-cli/issues/6)
+- [#10 observer: static mission-control viewer over fixture bundle](https://github.com/danielgwilson/mimetic-cli/issues/10)
+- [#5 feedback: specify public issue-draft CLI command](https://github.com/danielgwilson/mimetic-cli/issues/5)
+- [#15 skill: package agent setup guidance for installing Mimetic](https://github.com/danielgwilson/mimetic-cli/issues/15)
+- [#17 release: open-source readiness, package metadata, license, and publish dry-run](https://github.com/danielgwilson/mimetic-cli/issues/17)
+
+## Stage 1: Package Scaffold
+
+Build the minimum npm package:
+
+- `package.json`;
+- TypeScript config;
+- `src/cli.ts`;
+- `commander`;
+- test runner;
+- lint/typecheck/check scripts;
+- binary name `mimetic`;
+- stable JSON command envelope.
+
+Proof:
+
+```bash
+pnpm install
+pnpm check
+pnpm mimetic -- --help
+```
+
+## Stage 2: Project Layout And Init
+
+Implement `mimetic init`:
+
+- creates committed `mimetic/`;
+- creates ignored `.mimetic/`;
+- writes starter synthetic personas/scenarios/policies;
+- patches `package.json` scripts;
+- updates `.gitignore`;
+- supports `--dry-run`, `--yes`, and `--json`.
+
+Proof:
+
+```bash
+pnpm test
+pnpm mimetic -- init --dry-run --json
+```
+
+Fixture proof should run against a temporary app fixture, not this repo only.
+
+## Stage 3: Run Bundle And Verify
+
+Implement a synthetic dry-run bundle:
+
+- run id;
+- manifest;
+- scenario/persona selection;
+- lifecycle events;
+- review skeleton;
+- redaction result;
+- artifact paths;
+- source/git state.
+
+Implement `mimetic verify` over that bundle.
+
+Proof:
+
+```bash
+pnpm mimetic -- run --dry-run --json
+pnpm mimetic -- verify --run latest --json
+```
+
+## Stage 4: Observer
+
+Status: upgraded from static report to mission-control substrate for synthetic
+stream contracts.
+
+Implemented:
+
+- normalized `observer/observer-data.json` view model;
+- `events.ndjson` event stream contract;
+- stream-shaped sim lanes for UI, CLI, TUI, and Codex UI;
+- localhost watch server with no-store polling;
+- mission-control grid and focus mode;
+- terminal/TUI transcript stage;
+- evidence rail for events, artifacts, and gaps;
+- public-safe Codex UI stream contract with no raw provider payloads.
+
+Still next:
+
+- real browser actor adapter;
+- real PTY capture;
+- native Codex app-server adapter;
+- screenshot/trace gallery from real products;
+- reviewer acceptance gates over live product behavior.
+
+Proof:
+
+```bash
+pnpm mimetic -- watch
+```
+
+If browser verification is added, use screenshots of the observer as proof.
+
+## Stage 5: Feedback Issue Draft
+
+Status: implemented for the synthetic dry-run bundle path.
+
+Implement:
+
+```bash
+mimetic feedback draft --run latest --json
+mimetic feedback issue --run latest --repo owner/repo --format markdown
+mimetic feedback issue-url --run latest --repo owner/repo
+```
+
+Rules:
+
+- no GitHub API mutation;
+- no tokens;
+- no Projects;
+- redaction must pass;
+- dry-run-only claims are labeled as contract proof, not product proof;
+- issue body includes `mimetic_feedback` block.
+
+Proof:
+
+```bash
+pnpm mimetic -- feedback issue --run latest --repo example/app --format markdown
+```
+
+## Stage 6: Agent Skill
+
+Status: implemented as an installer-visible skills.sh skill under
+`skills/mimetic-cli/SKILL.md`.
+
+Create a shareable skill package that teaches agents to install and configure
+Mimetic in target repos.
+
+It should cover:
+
+- `npm i -D mimetic-cli`;
+- `npx mimetic init`;
+- committed vs ignored layout;
+- public-safety rules;
+- creating personas;
+- creating scenarios;
+- adding E2B/OpenAI env var names without values;
+- running doctor/run/watch/verify/feedback issue;
+- troubleshooting.
+
+Proof:
+
+```bash
+DISABLE_TELEMETRY=1 npx skills add . --list
+```
+
+Future proof: fresh-agent fixture follows the skill and reaches dry-run +
+issue draft.
+
+## Stage 6.5: Release Readiness
+
+Status: public package candidate, blocked only on explicit publish approval.
+
+Readiness lives in
+[`docs/release/open-source-readiness.md`](../release/open-source-readiness.md).
+The package has MIT metadata and public npm package shape. `npm publish`
+remains a human release action.
+
+## Stage 6.75: Self-Dogfood Config
+
+Status: implemented for dry-run contract proof.
+
+The repository now includes committed `mimetic/` source files so Mimetic can run
+against `mimetic-cli` itself. This makes `doctor` green on the repo, lets
+dry-run bundles read and digest `mimetic/personas/synthetic-new-user.yaml` and
+`mimetic/scenarios/first-run-smoke.yaml`, and keeps the live Codex TUI actor gap
+explicit. The live Codex TUI dogfood path and noninteractive `codex-exec`
+fanout hardening are tracked in
+[#28](https://github.com/danielgwilson/mimetic-cli/issues/28).
+
+## Stage 6.8: One-Command Watch UX
+
+Status: implemented for synthetic contract-proof stream lanes.
+
+`mimetic watch` now creates a fresh four-lane synthetic run, renders Observer,
+starts a localhost watch server, opens the served Observer in the browser, and
+keeps the shell attached. The CI-safe form is `mimetic watch --json --no-open`.
+`--sims <n>` remains the explicit scale control, and `--run <id>` watches
+existing evidence.
+
+## Stage 6.9: OSS Meta-Lab
+
+Status: implemented as an experimental live Observer-of-Observers bootstrap
+with a retained disposable smoke harness.
+
+`mimetic lab oss` opens the top-level Observer for public OSS meta-sims. Each
+lane is assigned a public GitHub `owner/repo` slug from `--repos` or repeated
+`--repo` values and carries the headed E2B desktop + Codex TUI bootstrap prompt
+for setting up Mimetic inside that repo and keeping the nested Observer visible.
+When live keys are present, Mimetic launches E2B desktops, uploads the locally
+packed Mimetic package, starts visible bootstrap terminals, clones each assigned
+repo inside the desktop, runs nested Mimetic setup/proof commands, attempts a
+Codex TUI pass, and opens the nested Observer in the sandbox browser.
+
+`mimetic lab oss-smoke` keeps the earlier clone/discard proof loop: shallow
+clone lightweight public GitHub repositories into ignored `.mimetic/tmp`, apply
+Mimetic setup in disposable clones, run the four-lane synthetic Observer proof,
+verify it, record git-status evidence, write an ignored
+`.mimetic/lab/oss/<run-id>/` report, and remove clones by default.
+
+Proof:
+
+```bash
+pnpm mimetic -- lab oss --detach --open --repos developit/mitt,lukeed/clsx
+pnpm mimetic -- lab oss --dry-run --json --no-open --repos developit/mitt,lukeed/clsx
+pnpm mimetic -- lab oss-smoke --limit 1 --json
+```
+
+Next substrate work: poll the remote bootstrap logs and nested Observer health
+back into the top-level bundle so the Observer can graduate each lane from
+`running` to explicit `passed` or `failed` without relying on a human watching
+the E2B stream.
+
+## Stage 7: Local Browser And First Real Adapter
+
+Only after the package and dry-run path are stable:
+
+- local app target detection;
+- Playwright/browser substrate;
+- first scripted browser scenario;
+- browser-app adapter fixture.
+
+Proof:
+
+- real browser screenshots in `.mimetic/runs`;
+- observer renders screenshots;
+- `verify` validates bundle.
+
+## Non-Goals For V0
+
+- live E2B;
+- OpenAI computer-use actor;
+- live GitHub mutation;
+- hosted queues/databases/webhooks;
+- provider spend;
+- production deploys;
+- real user/persona data;
+- private upstream artifacts.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "mimetic-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
+  "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [
     "agent-harness",
     "cli",
@@ -27,11 +28,22 @@
     "mimetic": "./dist/cli.js"
   },
   "files": [
+    "AGENTS.md",
     "dist",
+    "docs/architecture",
     "docs/assets",
+    "docs/contracts",
+    "docs/goals",
+    "docs/principles",
+    "docs/product",
+    "docs/ramp",
+    "docs/release",
+    "docs/roadmap",
     "skills",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
   ],
   "publishConfig": {
     "access": "public"

package/skills/mimetic-cli/SKILL.md

@@ -12,7 +12,7 @@ private artifacts. Keep every example synthetic and public-safe.
 
 Never read, copy, commit, summarize, or generate PII, PHI, secrets, keys,
 tokens, raw private transcripts, private screenshots, raw customer data, raw
-patient data, or private source-system artifacts.
+patient data, or private upstream artifacts.
 
 Do not edit `.env` or secret files. Do not paste credential values. Use env var
 names only, usually `OPENAI_API_KEY` and `E2B_API_KEY`. Stop before live