minutework 0.1.3 → 0.1.5

package/EXTERNAL_ALPHA.md

@@ -2,21 +2,71 @@
 
 This document is the operator-facing onboarding contract for the first external MinuteWork CLI alpha.
 
-## Success path
+## Supported paths
 
-The supported path is:
+Every supported external path starts with the same workspace/bootstrap flow:
 
 ```bash
 npx minutework init my-site --starter tenant-app
 cd my-site
 npx minutework login
 npx minutework link
-npx minutework dev
-npx minutework test
-npx minutework deploy --preview
 ```
 
-Anything outside that path is intentionally deferred.
+From there, the current external alpha supports two post-link lanes.
+
+### Developer-local broker lane
+
+Use `minutework session` when you want MinuteWork to assemble the workspace
+snapshot, choose a local workflow mode, and optionally launch the first shipped
+local coding engine.
+
+```bash
+minutework session start --mode human
+minutework session start --mode ai --engine claude
+minutework session status
+minutework session resume
+```
+
+- `start` stores or updates the workspace preference, writes a bounded context
+  pack, and launches Claude when `--mode ai --engine claude` is selected.
+- `status` prints the stored preference, current-session summary, and live lock
+  state as JSON.
+- `resume` reuses the stored workspace preference and launches a fresh broker
+  session without accepting mode or engine overrides.
+- `human` and `ai` are alternative start modes, not a required sequence.
+- Claude is the only supported local coding engine today.
+- AI mode now auto-installs and auto-updates managed Claude Code under the
+  machine-local MinuteWork CLI state root and prefers that managed binary over
+  any `claude` already on `PATH`.
+- Claude authentication still happens outside MinuteWork. If Claude needs local
+  login or approval, complete that in Claude itself and rerun the MinuteWork
+  broker command.
+
+The broker state model is intentionally split:
+
+- repo-local pointer and lock state under `.minutework/` tracks the current
+  workspace session
+- machine-local preferences, per-session context packs, transcripts, and
+  session history stay under the MinuteWork CLI state root
+
+The broker fails closed when a live session is already active, the selected
+engine is missing, a prior running record has gone stale, or the launch is
+interrupted or fails mid-session.
+
+### Local preview and deploy lane
+
+Use the existing local preview/test loop and hosted preview deploy lane when
+you want to run the generated app locally or submit a hosted preview:
+
+```bash
+minutework dev
+minutework test
+minutework deploy --preview
+```
+
+Anything outside these lanes remains deferred, including `--live`,
+runtime-backed deploy targets, and additional local coding engines.
 
 If you run `minutework init` **without** `--starter` in an interactive terminal, the CLI prompts for tenant-app, sidecar, both, or base-only. In CI or scripts, use `--starter` or set `MW_CLI_NONINTERACTIVE=1` to skip the prompt (base-only scaffold).
 
@@ -63,6 +113,9 @@ The CLI does not fabricate success. If the backend cannot materialize a hosted p
 
 - Missing auth: run `minutework login`
 - Missing binding: run `minutework link`
+- Missing stored broker preference before resume: run `minutework session start --mode <human|ai>`
+- Missing Claude binary or local Claude auth for AI mode: let MinuteWork retry the managed install when network access is available, or complete Claude authentication locally, then rerun `minutework session start --mode ai --engine claude`
+- Live or stale local broker session state: inspect `minutework session status`, let the live process exit, or rerun `minutework session resume`
 - Missing property-scoped release metadata: fix `tenant-app/.env.example` and re-run `minutework compile`
 - Unsupported release class: external alpha only supports hosted `ssr_container`
 - Missing provider/receipt substrate: deploy returns a typed failure receipt

package/README.md

@@ -1,15 +1,16 @@
 # `minutework`
 
-MinuteWork CLI for initializing a workspace, authenticating against a MinuteWork platform, linking a repo to a tenant-scoped public-site property, running local preview/test loops, and submitting hosted preview deploys.
+MinuteWork CLI for initializing a workspace, authenticating against a MinuteWork platform, linking a repo to a tenant-scoped public-site property, launching developer-local session broker flows, running local preview/test loops, and submitting hosted preview deploys.
 
 ## External alpha scope
 
 The current external alpha is intentionally narrow:
 
 - Starter: `tenant-app`
+- Developer-local broker surface: `minutework session start|resume|status`
 - Hosted release class: `ssr_container`
 - Deploy surface: `minutework deploy --preview`
-- Deferred: `--live`, sidecar/runtime-backed deploys, marketplace publish flows
+- Deferred: `--live`, additional local coding engines, sidecar/runtime-backed deploys, marketplace publish flows
 
 The CLI fails closed when the backend cannot provide typed release metadata, deploy status, receipts, activation state, or rollback state. It does not claim a successful deploy when the provider substrate is unavailable.
 
@@ -27,16 +28,58 @@ npm install --global minutework@alpha
 
 The package currently ships on a `0.x` alpha channel. Publish from this repo with the manual GitHub Actions workflow at `.github/workflows/minutework-cli-alpha-publish.yml`.
 
-## External alpha path
+## External alpha paths
+
+Start with the shared setup:
 
 ```bash
 npx minutework init my-site --starter tenant-app
 cd my-site
 npx minutework login
 npx minutework link
-npx minutework dev
-npx minutework test
-npx minutework deploy --preview
+```
+
+After `link`, the current alpha has two supported lanes.
+
+### Developer-local broker lane
+
+Use this lane when you want MinuteWork to assemble a bounded workspace context,
+persist broker state locally, and either prepare a human-mode session or launch
+the first supported local coding engine.
+
+```bash
+minutework session start --mode human
+minutework session start --mode ai --engine claude
+minutework session status
+minutework session resume
+```
+
+- `human` and `ai` are alternative start modes, not a required sequence.
+- Claude is the only supported local coding engine today.
+- AI mode launches Claude with explicit workspace MCP bootstrap plus a bounded
+  MinuteWork context pack instead of relying on implicit shell state.
+- MinuteWork now installs and updates managed Claude Code automatically under
+  the machine-local CLI state root when AI mode needs it, and prefers that
+  managed Claude binary over any `claude` already on `PATH`.
+- Claude authentication still happens outside MinuteWork. If Claude needs local
+  login or account approval, complete that in Claude itself and rerun the
+  MinuteWork session command.
+- Current-session coordination stays repo-local under `.minutework/`, while
+  preferences, per-session context packs, transcripts, and session history stay
+  machine-local under the MinuteWork CLI state root.
+- The broker fails closed on live overlap, missing engine binaries, stale
+  session records, interrupts, and launch failures instead of allowing
+  overlapping phantom sessions.
+
+### Local preview and deploy lane
+
+Use this lane when you want the workspace-local preview/test loop or a hosted
+preview deploy:
+
+```bash
+minutework dev
+minutework test
+minutework deploy --preview
 ```
 
 `link` provisions or resolves the default published-site property for the active tenant and stores that property key in repo-local state. The generated `tenant-app/.env.example` defaults to `MW_PUBLIC_SITE_PROPERTY_KEY=main-site` and `MW_PUBLIC_SITE_ENV=preview`.

package/dist/managed-engine.d.ts

@@ -0,0 +1,52 @@
+import type { CliStatePaths, PlatformName } from "./paths.js";
+export declare const MANAGED_CLAUDE_PACKAGE_NAME = "@anthropic-ai/claude-code";
+export declare const MANAGED_CLAUDE_UPDATE_TTL_MS: number;
+export type ManagedEngineSource = "managed" | "path";
+export type ManagedEngineInstallStatus = "current" | "installed" | "missing" | "path_fallback" | "update_failed_reused" | "updated";
+export type EngineCommandRunner = (options: {
+    args: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    program: string;
+}) => Promise<{
+    exitCode: number | null;
+    stderr: string;
+    stdout: string;
+}>;
+export type ManagedClaudeReadiness = {
+    detail: string;
+    engineInstallStatus: "missing";
+    engineSource: null;
+    engineVersion: null;
+    executablePath: null;
+    status: "missing_binary";
+    warnings: string[];
+} | {
+    detail: string;
+    engineInstallStatus: Exclude<ManagedEngineInstallStatus, "missing">;
+    engineSource: ManagedEngineSource;
+    engineVersion: string | null;
+    executablePath: string;
+    status: "ready";
+    warnings: string[];
+};
+export type ManagedClaudePaths = {
+    executablePath: string;
+    lockPath: string;
+    metadataPath: string;
+    packageJsonPath: string;
+    packageRoot: string;
+    workspaceRoot: string;
+};
+type ResolveExecutable = (program: string) => Promise<string | null>;
+export declare function resolveManagedClaudePaths(paths: CliStatePaths): ManagedClaudePaths;
+export declare function ensureManagedClaudeReadiness(options: {
+    cliStatePaths: CliStatePaths;
+    env: NodeJS.ProcessEnv;
+    isProcessAlive?: (pid: number) => boolean;
+    now?: () => Date;
+    platform: PlatformName;
+    resolveExecutable: ResolveExecutable;
+    runCommand?: EngineCommandRunner;
+}): Promise<ManagedClaudeReadiness>;
+export {};