humanish 0.0.1 → 0.15.0

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

@@ -0,0 +1,311 @@
+# World-Class Open-Source V0 Roadmap
+
+Date: 2026-06-01
+
+Status: HISTORICAL (banner added 2026-06-11). This was the staged v0 build
+plan; it is kept as delivery history and is not maintained. Several "Non-Goals
+For V0" have since shipped as explicit opt-ins (the OpenAI computer-use actor,
+live E2B desktop labs), and the lab schema is now `humanish.lab.v2`. For the
+live goal state read [`docs/goals/current.md`](../goals/current.md).
+
+## Target Outcome
+
+A maintainer can install `humanish` into a normal JavaScript app, let their
+coding agent run setup, and get a public-safe persona simulation harness with:
+
+- committed `humanish/` source plane;
+- ignored `.humanish/` 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 `humanish`;
+- 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 humanish binary](https://github.com/danielgwilson/humanish/issues/13)
+- [#14 init: scaffold committed humanish source and ignored .humanish runtime layout](https://github.com/danielgwilson/humanish/issues/14)
+- [#16 fixtures: create target app fixture for init, dry-run, verify, and observer proof](https://github.com/danielgwilson/humanish/issues/16)
+- [#7 cli: scaffold doctor, run --dry-run, review, verify, runs, and watch](https://github.com/danielgwilson/humanish/issues/7)
+- [#6 core: run IDs, artifact paths, git state, history, and lifecycle primitives](https://github.com/danielgwilson/humanish/issues/6)
+- [#10 observer: static mission-control viewer over fixture bundle](https://github.com/danielgwilson/humanish/issues/10)
+- [#5 feedback: specify public issue-draft CLI command](https://github.com/danielgwilson/humanish/issues/5)
+- [#15 skill: package agent setup guidance for installing Humanish](https://github.com/danielgwilson/humanish/issues/15)
+- [#17 release: open-source readiness, package metadata, license, and publish dry-run](https://github.com/danielgwilson/humanish/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 `humanish`;
+- stable JSON command envelope.
+
+Proof:
+
+```bash
+pnpm install
+pnpm check
+pnpm humanish -- --help
+```
+
+## Stage 2: Project Layout And Init
+
+Implement `humanish init`:
+
+- creates committed `humanish/`;
+- creates ignored `.humanish/`;
+- writes starter synthetic personas/scenarios/policies;
+- patches `package.json` scripts;
+- updates `.gitignore`;
+- supports `--dry-run`, `--yes`, and `--json`.
+
+Proof:
+
+```bash
+pnpm test
+pnpm humanish -- 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 `humanish verify` over that bundle.
+
+Proof:
+
+```bash
+pnpm humanish -- run --dry-run --json
+pnpm humanish -- 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 humanish -- 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
+humanish feedback draft --run latest --json
+humanish feedback issue --run latest --repo owner/repo --format markdown
+humanish 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 `humanish_feedback` block.
+
+Proof:
+
+```bash
+pnpm humanish -- feedback issue --run latest --repo example/app --format markdown
+```
+
+## Stage 6: Agent Skill
+
+Status: implemented as an installer-visible skills.sh skill under
+`skills/humanish/SKILL.md`.
+
+Create a shareable skill package that teaches agents to install and configure
+Humanish in target repos.
+
+It should cover:
+
+- `npm i -D humanish`;
+- `npx humanish 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 `humanish/` source files so Humanish can run
+against `humanish` itself. This makes `doctor` green on the repo, lets
+dry-run bundles read and digest `humanish/personas/synthetic-new-user.yaml` and
+`humanish/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/humanish/issues/28).
+
+## Stage 6.8: One-Command Watch UX
+
+Status: implemented for synthetic contract-proof stream lanes.
+
+`humanish 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 `humanish watch --json --no-open`.
+`--sims <n>` remains the explicit scale control, and `--run <id>` watches
+existing evidence.
+
+## Stage 6.8: Lab Manifests
+
+Status: implemented as the generic source shape for reusable runs.
+
+Humanish now resolves `.yaml` lab manifests from committed `humanish/labs/`,
+ignored `.humanish/labs/`, ignored `.humanish/local/labs/`, or an explicit
+`.yaml` path. The human path is `humanish watch <lab>`; the agent/CI path is
+`humanish lab run <lab> --json --no-open`; discovery is `humanish lab list` and
+`humanish lab inspect <lab>`.
+
+Private or maintainer-only dogfood belongs in ignored lab manifests plus
+explicit `--env-file`; the public package should not hardcode private target
+names or require broad inherited job env.
+
+## Stage 6.9: Maintainer OSS Meta-Lab
+
+Status: implemented as repo-owned `humanish/labs/oss.yaml` plus compatibility
+aliases, with a retained disposable smoke harness.
+
+`humanish watch oss` opens the top-level Observer for authorized-repo meta-sims.
+Each lane is assigned a GitHub `owner/repo` slug from `--repos` or repeated
+`--repo` values and carries a headed E2B desktop for setting up Humanish inside
+that repo, starting the target app where feasible, and keeping the nested
+Observer visible.
+Default public targets should be apps, CLIs, or agent-facing tools with
+observable user surfaces. Frameworks, starters, and utility libraries are
+acceptable only when the explicit scenario is developer-experience testing.
+When live keys are present, Humanish launches E2B desktops, uploads the locally
+packed Humanish package, starts visible bootstrap terminals, clones each assigned
+repo inside the desktop, runs nested Humanish setup/proof commands, opens
+desktop/mobile app windows plus the nested Observer in the sandbox browser, and
+starts a nonblocking Codex actor attempt. Attached watch mode overlays live E2B
+stream URLs only in memory; durable run artifacts keep screenshots/status, not
+auth-bearing URLs. Private repos are maintainer-only, require an authorized
+runtime GitHub token, and redact repo labels in durable artifacts by default.
+
+`humanish lab run oss-smoke` keeps the earlier clone/discard proof loop: shallow
+clone lightweight public GitHub repositories into ignored `.humanish/tmp`, apply
+Humanish setup in disposable clones, run the four-lane synthetic Observer proof,
+verify it, record git-status evidence, write an ignored
+`.humanish/lab/oss/<run-id>/` report, and remove clones by default.
+
+Proof:
+
+```bash
+pnpm humanish -- watch oss --detach --open --repos CorentinTh/it-tools,drawdb-io/drawdb
+pnpm humanish -- lab run oss --dry-run --json --no-open --repos CorentinTh/it-tools,drawdb-io/drawdb
+pnpm humanish -- lab run oss-smoke --limit 1 --json
+```
+
+Next substrate work: upgrade nested app-url render proof into provider-backed
+browser personas that drive the target app and add richer process/filesystem
+telemetry for Codex actor health.
+
+## 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 `.humanish/runs`;
+- observer renders screenshots;
+- `verify` validates bundle.
+
+## Non-Goals For V0
+
+- live E2B as required first-run behavior;
+- OpenAI computer-use actor;
+- live GitHub mutation;
+- hosted queues/databases/webhooks;
+- provider spend as required first-run behavior;
+- production deploys;
+- real user/persona data;
+- private upstream artifacts.

package/package.json

@@ -1,15 +1,109 @@
 {
   "name": "humanish",
-  "version": "0.0.1",
-  "description": "Reserved for the humanish persona-simulation harness (formerly homun): run realistic synthetic users against your app from any project directory. Rename in progress; real package lands here shortly.",
+  "version": "0.15.0",
+  "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",
+    "persona-simulation",
+    "ui-testing",
+    "ux-research"
+  ],
+  "type": "module",
   "license": "MIT",
-  "author": "Daniel G Wilson",
-  "homepage": "https://github.com/danielgwilson/homun",
+  "packageManager": "pnpm@11.5.2",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "humanish": "./dist/cli.js"
+  },
+  "files": [
+    "AGENTS.md",
+    "dist",
+    "docs/architecture",
+    "docs/assets",
+    "docs/contracts",
+    "docs/goals/current.md",
+    "docs/principles",
+    "docs/product",
+    "docs/ramp",
+    "docs/release",
+    "docs/roadmap",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node --eval \"import('node:fs').then(({ chmodSync }) => chmodSync('dist/cli.js', 0o755))\"",
+    "check": "pnpm typecheck && pnpm test && pnpm build",
+    "humanish": "tsx src/cli.ts",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepack": "pnpm build",
+    "public-surface:scan": "node scripts/public-surface-scan.mjs",
+    "release:check": "pnpm check && pnpm public-surface:scan && pnpm skill:check && npm pack --dry-run",
+    "skill:check": "DISABLE_TELEMETRY=1 npx skills add . --list",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "humanish:doctor": "pnpm humanish -- doctor",
+    "humanish:run": "pnpm humanish -- run --dry-run",
+    "humanish:watch": "pnpm humanish -- watch",
+    "humanish:watch:ci": "pnpm humanish -- watch --json --no-open",
+    "humanish:dogfood": "pnpm humanish -- watch",
+    "humanish:verify": "pnpm humanish -- verify",
+    "humanish:feedback": "pnpm humanish -- feedback issue --repo danielgwilson/humanish",
+    "humanish:lab:list": "pnpm humanish -- lab list",
+    "humanish:lab:oss": "pnpm humanish -- lab run oss",
+    "humanish:lab:oss:ci": "pnpm humanish -- lab run oss --dry-run --json --no-open",
+    "humanish:lab:oss:smoke": "pnpm humanish -- lab run oss-smoke"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/danielgwilson/homun.git"
+    "url": "https://github.com/danielgwilson/humanish.git"
+  },
+  "bugs": {
+    "url": "https://github.com/danielgwilson/humanish/issues"
+  },
+  "homepage": "https://github.com/danielgwilson/humanish#readme",
+  "dependencies": {
+    "commander": "^14.0.3",
+    "playwright-core": "^1.60.0",
+    "pngjs": "^7.0.0",
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.0",
+    "@e2b/desktop": "^2.2.3"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    },
+    "@e2b/desktop": {
+      "optional": true
+    }
   },
-  "keywords": ["persona-simulation", "synthetic-users", "testing-harness", "computer-use"],
-  "files": ["README.md", "index.js"],
-  "main": "index.js"
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.0",
+    "@e2b/desktop": "^2.2.3",
+    "@types/node": "^20.19.41",
+    "@types/pngjs": "^6.0.5",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  }
 }

package/skills/humanish/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: humanish
+description: Install and configure Humanish CLI in a JavaScript app as an open-source-safe persona simulation harness. Use when an agent needs to add humanish, run safe first setup, create synthetic personas or scenarios, configure env var names without values, run verification and Observer commands, or draft public-safe feedback issues without GitHub mutation.
+---
+
+# Humanish CLI
+
+Use this skill to add Humanish to a target app without relying on chat memory or
+private artifacts. Keep every example synthetic and public-safe.
+
+## Hard Boundary
+
+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 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`. For live local runs,
+prefer an explicit ignored env file passed with `--env-file <path>`; do not
+assume broad inherited job env is safe. Stop before live provider spend,
+hosted execution, deploys, public tunnels, or GitHub mutation unless the user
+explicitly approves that exact action.
+
+## Setup Workflow
+
+1. Inspect public target-repo files only: `package.json`, docs, route/app
+   structure, test scripts, and `.gitignore`.
+2. Install Humanish with the repo's package manager:
+
+   ```bash
+   npm i -D humanish
+   ```
+
+   The package is `humanish`; the installed binary is `humanish`. After
+   installation, `npx humanish ...` resolves the local project binary. For a
+   one-shot command before installation, use
+   `npx --package humanish humanish ...` to guarantee the binary comes from
+   the `humanish` registry package rather than a same-named command already
+   on the PATH.
+
+3. Preview setup:
+
+   ```bash
+   npx humanish init --dry-run --json
+   ```
+
+4. Apply setup after the planned changes are understood:
+
+   ```bash
+   npx humanish init --yes --json
+   ```
+
+5. Confirm the layout:
+   - commit `humanish/` source files;
+   - ignore `.humanish/` runtime artifacts;
+   - keep committed labs under `humanish/labs/*.yaml`;
+   - keep private/local labs under ignored `.humanish/labs/*.yaml` or
+     `.humanish/local/labs/*.yaml`;
+   - keep `.env.example` commit-safe and value-free;
+   - never commit generated run bundles.
+
+## Format Stack
+
+When creating or editing Humanish files:
+
+- use `.yaml` for human-authored Humanish source: personas, scenarios,
+  policies, labs, review vocabulary, and milestones;
+- use `.ts` for executable integration: `humanish/config.ts`, adapters, route
+  catalogs, and app launch logic;
+- use `.json` or `.ndjson` for generated machine artifacts, Observer data, run
+  bundles, event streams, and synthetic fixtures.
+
+Do not create `.yml` files under `humanish/`; `.yml` is for outside ecosystem
+conventions such as GitHub Actions workflows. Do not introduce TOML unless the
+target project has a concrete scalar global-config need that YAML, TypeScript,
+or JSON does not serve.
+
+## Authoring Personas And Scenarios
+
+Create or edit only synthetic files under `humanish/`.
+
+Personas should describe motivations, accessibility needs, experience level,
+device assumptions, and risk tolerance. Avoid names, emails, addresses,
+accounts, screenshots, logs, tickets, transcripts, analytics rows, or anything
+copied from a real user.
+
+Scenarios should define the target app surface, start URL, task intent,
+success signals, and failure signals. Keep app-specific truth in the target
+repo's `humanish/` files, not in the package or this skill.
+
+When the app can run locally, make at least one scenario executable with a
+`browser.steps` manifest so `humanish run --app-url` can drive the app instead
+of falling back to the generic two-step proof:
+
+```yaml
+schema: humanish.scenario.v1
+id: product-core-flow
+title: Product core flow
+persona: synthetic-new-user
+goal: Reach and verify the first meaningful app state with synthetic data.
+mode: browser
+browser:
+  startPath: /
+  steps:
+    - id: open-home
+      label: Open the app
+      action: goto
+      path: /
+      expect:
+        text: "Get started"
+    - id: enter-synthetic-input
+      label: Enter synthetic fixture input
+      action: fill
+      selector: "input[name='query']"
+      value: "synthetic fixture"
+    - id: submit-primary-action
+      label: Submit the primary action
+      action: click
+      selector: "button[type='submit']"
+      expect:
+        stateChanged: true
+```
+
+Supported actions are `goto`, `fill`, `click`, `assertText`, `waitForText`,
+and `waitForSelector`. Supported expectations are `text`, `selectorVisible`,
+`urlIncludes`, and `stateChanged`. Use public-safe selectors and synthetic
+values only. Do not write real emails, names, customer data, tickets, logs, or
+tokens into scenario files.
+
+## Authoring Labs
+
+Create reusable simulation runs as `.yaml` lab manifests:
+
+```yaml
+schema: humanish.lab.v2
+id: first-run
+title: First-run synthetic Observer
+subject:
+  source: this-repo
+actors:
+  - type: synthetic-persona
+    count: 4
+scenario:
+  mode: dry-run
+defaults:
+  open: true
+```
+
+A lab is a composition (`subject` × `actors` × `execution` × `scenario` ×
+`policies`), not a hardcoded kind; there is no v1 compatibility. Run
+`npx humanish lab inspect <lab>` to see how a manifest parses, including
+warnings for fields the engine does not consume yet.
+
+Use committed `humanish/labs/*.yaml` for public-safe, reproducible labs. Use
+ignored `.humanish/labs/*.yaml` or `.humanish/local/labs/*.yaml` for private repo
+targets, local-only dogfood, or machine-specific settings. Never commit private
+repo names, stream URLs, credential values, screenshots, logs, source snippets,
+or operational details.
+
+Useful commands:
+
+```bash
+npx humanish lab list
+npx humanish lab inspect first-run
+npx humanish watch first-run
+npx humanish lab run first-run --json --no-open
+```
+
+## First Proof Run
+
+Run the no-credentials path first. This proves Humanish artifact plumbing, not
+target app behavior:
+
+```bash
+npx humanish doctor
+npx humanish watch
+npx humanish verify --run latest --json
+npx humanish feedback issue --run latest --repo example/app --format markdown
+```
+
+For CI or non-interactive proof:
+
+```bash
+npx humanish watch --json --no-open
+npx humanish lab run first-run --json --no-open
+```
+
+The feedback command prints a public-safe Markdown draft. It must not call the
+GitHub API, require a token, update Projects, use provider credits, or claim
+product behavior proof from a dry run.
+
+When the target app can run locally, prove real browser behavior with
+`run --app-url` after starting the app on loopback:
+
+```bash
+# in another terminal, start the target app on 127.0.0.1 or localhost
+npx humanish run --app-url http://127.0.0.1:<port> --sims 2 --json
+npx humanish verify --run latest --json
+npx humanish watch --run latest --detach --no-open --json
+```
+
+Do not use `humanish watch --sims ...` as a substitute for app-url proof.
+`watch` renders or follows Observer evidence; `run --app-url` is the command
+that captures live desktop/mobile browser evidence against a running app.
+
+## Optional Live E2B Lab
+
+Live headed E2B desktop lanes are optional. Add the substrate dependency only
+when the user explicitly wants live E2B execution:
+
+```bash
+npm i -D @e2b/desktop
+```
+
+Then confirm env var names are documented without values:
+
+```bash
+E2B_API_KEY
+OPENAI_API_KEY
+```
+
+Do not paste values into files, prompts, run bundles, issue drafts, or logs.
+Load local values only at invocation time:
+
+```bash
+npx humanish watch .humanish/labs/local-live.yaml --env-file .humanish/local/provider.env
+```
+
+When choosing dogfood targets, prefer apps, CLIs, or agent-facing tools with a
+real observable user surface and local run path. Do not use libraries,
+frameworks, starters, or infrastructure packages as default targets unless the
+declared scenario is developer-experience testing. Private repos are allowed
+only as explicit maintainer-authorized runs with repo redaction left on; never
+publish their names, screenshots, logs, source snippets, or operational details.
+
+## Reporting Back
+
+Report:
+
+- files changed in the target repo;
+- exact proof commands run;
+- generated local artifact paths under `.humanish/`;
+- whether redaction passed;
+- what remains blocked before live browser, OpenAI, E2B, or GitHub mutation.

package/skills/humanish/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Humanish CLI"
+  short_description: "Set up public-safe persona simulation"
+  default_prompt: "Use $humanish to install Humanish in this repo, scaffold synthetic personas and scenarios, run the safe Observer proof, and report the public-safe artifacts. If the app can run locally, start it on loopback and use `humanish run --app-url http://127.0.0.1:<port> --sims 2` before rendering Observer with `humanish watch --run latest`; do not treat `watch --sims` as app behavior proof."
+
+policy:
+  allow_implicit_invocation: true

package/index.js

@@ -1 +0,0 @@
-module.exports = {};