@repo-os/repoos 0.5.45

package/dist/commands/init.js

@@ -0,0 +1,699 @@
+/**
+ * `repoos init` — make any repo RepoOS-ready, idempotently. Safe to re-run: it
+ * never overwrites existing files, only creates what's missing.
+ *
+ * In a directory that is NOT inside a git repo, `repoos init` switches to a
+ * guided, interactive flow that creates a brand-new RepoOS project from
+ * scratch: optionally in a subdirectory, with a choice of layout (repo root
+ * vs. a `repoos/` subfolder, config file at root either way), an optional
+ * one-line project description (seeded into the sample task) and an optional
+ * initial commit.
+ */
+import { spawn } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
+import { createServer } from "node:net";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { deriveServePort, findRepoRoot, loadConfig } from "../core/config.js";
+import { gitAvailable, gitCommitAll, gitConfig, gitInit, isGitRepo } from "../core/git.js";
+import { c } from "../cli/colors.js";
+import { cmdServe } from "./serve.js";
+const SAMPLE_TASK = (description) => `---
+id: "0001"
+title: Set up RepoOS
+type: chore
+status: done
+priority: p2
+area: infra
+assigned_to: unassigned
+created_by: human
+branch: ""
+---
+${description ? `\n## Overview\n\n${description}\n` : ""}
+## Problem
+
+The repo needed a lightweight, repo-native way to track work that AI agents
+and humans share. Tasks live as markdown files, versioned in git.
+
+## Desired UX
+
+Run \`repoos list\` to see the board. Run \`repoos show 0001\` to read a task
+(this one). Agents read these files directly for full context.
+
+## Acceptance criteria
+
+- [x] \`repoos init\` scaffolded work/, repoos.toml, AGENTS.md
+- [x] \`repoos list\` shows this task
+- [x] Editing the \`status:\` field moves it across the board
+
+This task exists to show you the shape of a task file — it's done because
+running \`repoos init\` already satisfies everything above. There's nothing to
+"work" here; move on to your next task.
+
+## Notes for AI
+
+Status is a frontmatter field — never move files between folders. Keep diffs
+small. Read AGENTS.md before starting any task.
+`;
+/**
+ * The first *workable* task a guided new-project init leaves on the board.
+ * 0001 is deliberately `done` (scaffolding is the whole of it), so this is what
+ * a new user — or their first agent — actually picks up. `repoos init` runs
+ * before any server or agent exists, so the body itself is the prompt: it
+ * embeds the one-line description collected at init and carries the questions
+ * that turn that description into docs and real tasks later.
+ */
+const NEW_PROJECT_STARTER_TASK = (id, description) => `---
+id: "${id}"
+title: Flesh out the product vision and initial architecture
+type: spec
+status: ready
+priority: p2
+area: product
+assigned_to: unassigned
+created_by: human
+branch: ""
+---
+## Overview
+
+This project started from a one-line description. This task turns it into
+something a team can actually build from — a shared vision, an initial
+architecture, and a first batch of concrete work.
+
+## Project description
+
+${description
+    ? `> ${description}`
+    : "_No description was given at init time. Start by writing one line that says what this project is and who it's for._"}
+
+## What to do
+
+1. Read the description above and the rest of this repo.
+2. Work through the questions that block design — on your own, or with the
+   project's owner:
+   - Who is this for, and what is the smallest useful first release?
+   - What stack and hosting, and why those over the alternatives?
+   - What is explicitly **out of scope** for now?
+3. Write the answers into \`docs/\` — at minimum a short vision note and an
+   architecture note. Keep them specific to this project.
+4. Break the result into a handful of concrete tasks with
+   \`repoos new "<title>"\`, and move the ones that are ready into \`ready\`.
+5. Record the docs you wrote here, then move this task to \`review\` (or
+   \`done\` if there is genuinely nothing left to capture).
+
+## Notes for AI
+
+This task is self-contained: the description above and the questions in step 2
+are the prompt. Ask the human before inventing answers about stack, scope or
+priorities — a short back-and-forth here saves a lot of rework later.
+`;
+/**
+ * The first workable task for `repoos init` inside an existing codebase. There
+ * is already a repo to read, so unlike the new-project starter this one is
+ * about documenting what exists and turning the gaps into a real backlog.
+ */
+const EXISTING_REPO_STARTER_TASK = (id) => `---
+id: "${id}"
+title: Read this codebase and propose docs/ + an initial task backlog
+type: spec
+status: ready
+priority: p2
+area: docs
+assigned_to: unassigned
+created_by: human
+branch: ""
+---
+## Overview
+
+RepoOS was just added to an existing codebase. The first useful move is to read
+what's already here, write down what a newcomer — human or agent — would need,
+then turn what's missing into work.
+
+## What to do
+
+1. Scan the repo: top-level structure, languages and frameworks, build and
+   test commands, and any existing conventions or docs.
+2. Write the durable findings into \`docs/\` — architecture notes and the
+   conventions anyone working here must follow.
+3. Draft a small starter backlog of real tasks with \`repoos new "<title>"\`,
+   each concrete enough to work on its own.
+4. Record what you wrote here, then move this task to \`review\` (or \`done\` if
+   there is nothing left to capture).
+
+## Notes for AI
+
+Read \`AGENTS.md\` first — it's the operating loop for this repo. Base the docs
+on what the code actually does rather than what you'd expect it to; where the
+repo is silent, write down the open question instead of guessing.
+`;
+const AGENTS_MD = `# AGENTS.md
+
+This repo uses **RepoOS**: tasks are markdown files under \`work/\`, and the
+repo itself is the source of truth. This file tells AI agents how to operate.
+
+## Operating loop
+
+1. Read this file and any relevant docs under \`docs/\`.
+2. Pick a task from \`work/\` whose \`status: ready\`.
+3. Set its \`status: active\` (edit the frontmatter; do not move the file).
+4. Create a worktree on the branch named in the task's \`branch:\` field, or set one.
+5. Implement → test → if the repo has a git remote, open an MR/PR against main.
+6. Set \`status: review\` when ready for human sign-off. **Leave the worktree open; do NOT merge its branch.**
+
+## Review and sign-off
+
+A \`review\` task stays in its open worktree until a human (or another AI) signs
+off; the implementer never merges to \`main\` at \`review\` time.
+
+- No git remote: on approval, the reviewer says **"move task <id> to done"**. The
+  implementer then sets \`status: done\` (commit \`docs(<id>): set status done\`),
+  fast-forward merges the branch to \`main\`, removes the worktree, and deletes
+  the branch.
+- With a git remote: an MR/PR is opened against \`main\` at \`review\` time. On
+  approval it is merged by the reviewer (or by the implementer only on "move task
+  <id> to done"), then remote + local branches are deleted and \`status\` is set
+  to \`done\`.
+- Requested changes are fixed on the same worktree, tests re-run, and the task
+  re-set to \`review\`.
+- If the \`reviewer\` agent is enabled on the Agents page, RepoOS reviews the
+  task automatically when it lands in \`review\` and shows a short report (bugs,
+  edge cases, suggestions) in the task drawer. It is advisory: the human still
+  reviews and is the only one who moves a task to \`done\`.
+
+## Rules
+
+- **Never** move task files between folders. Status lives in frontmatter.
+- **Never write directly to \`work/*.md\` files.** All task creation and
+  manipulation goes through \`repoos\` commands or HTTP API endpoints
+  (\`POST /api/tasks\`, \`PATCH /api/tasks/:id\`, etc.). If the RepoOS server
+  is unreachable, stop and report the issue — do not hand-write task files.
+- **The Product Manager agent is authorized to create and update tasks.** It
+  must use those same RepoOS CLI commands or HTTP API endpoints for task body,
+  metadata, and status changes; it must never edit task Markdown directly.
+- **Never** deploy to production without human sign-off.
+- Keep frontmatter tidy; \`repoos\` will normalize key order on write.
+- One task = one focused worktree.
+
+## Conventions
+
+Document stack-specific conventions here (framework, lint, test commands).
+
+## UI previews are server-owned
+
+Never run \`repoos serve\` yourself and never pick a port — RepoOS owns the
+control-plane port and every preview port, and direct serve attempts from agent
+processes are rejected. Preview requests are the human's to make — do NOT
+automatically request a preview before handoff or as a routine part of finishing
+a task. If the human explicitly asks you to verify a change the way a browser
+would see it, request this task's managed preview by emitting the exact signal
+line (idempotent, and no localhost or curl is required — your sandbox may have
+no network access to the control plane):
+
+    ::repoos-preview-request::
+
+RepoOS validates the request against your live run, starts the preview from
+your worktree, probes it server-side, and records the preview URL and probe
+result in your task transcript. The preview is reaped when the task leaves
+active/review.
+`;
+function repoosToml(layout) {
+    const ns = layout === "repoos"
+        ? `workDir = "repoos/work"\ndocsDir = "repoos/docs"\ncacheDir = "repoos/.repoos"\n`
+        : "";
+    return `# RepoOS configuration. All fields optional — these are the defaults.
+
+${ns}defaultStatus = "inbox"
+defaultAssignee = "unassigned"
+
+# Optional features, off by default — uncomment to turn them on. Real
+# secrets (API keys, client secrets) go in .env, never here (this file is
+# git-tracked); see .env.example for the matching variables.
+
+# [auth]                                # require login (email OTP / Google) — docs/native-auth.md
+# enabled = true
+# bootstrapAdmin = "you@example.com"    # only this email can claim the first admin account
+#
+# [auth.emailProvider]
+# type = "resend"
+# fromAddress = "noreply@yourdomain.com"
+#
+# [auth.google]                         # optional — adds a "Sign in with Google" button
+# clientId = "..."                      # clientSecret goes in .env, not here
+
+# [whisper]                             # voice-to-text in text areas
+# provider = "groq"                     # or "openai"
+
+# ntfyEnabled = true                    # push notifications on task lifecycle events
+# ntfyTopic = "repoos_myproject"
+# ntfyBaseUrl = "https://ntfy.sh"       # or your self-hosted ntfy server
+`;
+}
+const ENV_EXAMPLE = `# Copy to .env and fill in what you need — .env is gitignored, this file is
+# tracked so the repo documents which secrets a full setup expects.
+# repoos serve auto-loads .env at startup; real shell/process-supervisor env
+# vars still take precedence over it.
+
+# --- Auth (docs/native-auth.md) — only used when [auth].enabled = true ---
+# REPOOS_RESEND_API_KEY=re_...
+# REPOOS_GOOGLE_CLIENT_SECRET=...
+# REPOOS_AUTH_SESSION_SECRET=...          # auto-generated on first boot if omitted
+
+# --- Voice-to-text transcription (only used when [whisper] is configured) ---
+# REPOOS_WHISPER_KEY=...                  # or GROQ_API_KEY / OPENAI_API_KEY directly
+
+# --- repoos tunnel (Cloudflare Tunnel + Access) ---
+# CLOUDFLARE_API_TOKEN=...
+
+# --- ntfy.sh push notifications ---
+# NTFY_BASE_URL=https://ntfy.sh          # or your self-hosted ntfy server
+`;
+const INITIAL_COMMIT_MSG = "chore: initialize RepoOS project";
+const STARTER_TASK = {
+    new: { slug: "flesh-out-the-vision", build: NEW_PROJECT_STARTER_TASK },
+    existing: { slug: "read-the-codebase", build: (id) => EXISTING_REPO_STARTER_TASK(id) },
+};
+/**
+ * Next free 4-digit task id for a scaffolded file, derived from the ids that
+ * already exist under `workDir` (matching the numbering scheme used by
+ * `createTask`). 0001 is written just before this runs, so a fresh scaffold
+ * gets 0002; a repo that already has tasks gets the next id past the highest.
+ */
+function nextScaffoldId(root, workDir) {
+    let max = 0;
+    try {
+        for (const name of readdirSync(join(root, workDir))) {
+            const m = name.match(/^(\d+)/);
+            if (m)
+                max = Math.max(max, parseInt(m[1], 10));
+        }
+    }
+    catch {
+        /* workDir doesn't exist yet — start from zero */
+    }
+    return String(max + 1).padStart(4, "0");
+}
+/**
+ * Locate an already-seeded starter task by its slug suffix. Init is
+ * idempotent, so once the starter exists a re-run must not write another one —
+ * and crucially, must not compute a *new* id every time (which would append a
+ * fresh 0002, 0003, … starter on each run).
+ */
+function findStarter(root, workDir, slug) {
+    try {
+        const match = readdirSync(join(root, workDir)).find((n) => n.endsWith(`-${slug}.md`));
+        return match ? join(workDir, match).split("\\").join("/") : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function scaffoldInto(root, description, layout = "root", kind = "new") {
+    const created = [];
+    const skipped = [];
+    const ensureDir = (rel) => {
+        const p = join(root, rel);
+        if (!existsSync(p)) {
+            mkdirSync(p, { recursive: true });
+            created.push(rel + "/");
+        }
+        else {
+            skipped.push(rel + "/");
+        }
+    };
+    const ensureFile = (rel, content) => {
+        const p = join(root, rel);
+        if (!existsSync(p)) {
+            writeFileSync(p, content);
+            created.push(rel);
+        }
+        else {
+            skipped.push(rel);
+        }
+    };
+    // Write config first so workDir/docsDir/cacheDir overrides are in effect
+    // before the dirs are created (namespace layout) — or so an existing
+    // config is respected untouched (existing-repo path).
+    ensureFile("repoos.toml", repoosToml(layout));
+    const config = loadConfig(root);
+    ensureDir(config.workDir);
+    ensureDir(config.docsDir);
+    ensureFile("AGENTS.md", AGENTS_MD);
+    ensureFile(join(config.workDir, "0001-set-up-repoos.md"), SAMPLE_TASK(description));
+    // 0001 is `done` (scaffolding is all of it), so without this the ready
+    // column is empty right after init. Seed one genuinely workable task; its
+    // id follows whatever is already on the board.
+    const starter = STARTER_TASK[kind];
+    const existingStarter = findStarter(root, config.workDir, starter.slug);
+    if (existingStarter) {
+        skipped.push(existingStarter);
+    }
+    else {
+        const starterId = nextScaffoldId(root, config.workDir);
+        ensureFile(join(config.workDir, `${starterId}-${starter.slug}.md`), starter.build(starterId, description));
+    }
+    ensureFile(".env.example", ENV_EXAMPLE);
+    // gitignore the derived cache and local secrets
+    const giPath = join(root, ".gitignore");
+    const ignoreLines = [
+        { comment: "# RepoOS derived index cache", line: `${config.cacheDir}/` },
+        { comment: "# Local secrets — see .env.example", line: ".env" },
+    ];
+    const existingLines = existsSync(giPath) ? readFileSync(giPath, "utf8").split(/\r?\n/) : [];
+    const toAdd = ignoreLines.filter((l) => !existingLines.some((e) => e.trim() === l.line));
+    if (toAdd.length === 0) {
+        skipped.push(".gitignore");
+    }
+    else if (existsSync(giPath)) {
+        appendFileSync(giPath, "\n" + toAdd.map((l) => `${l.comment}\n${l.line}`).join("\n\n") + "\n");
+        created.push(".gitignore (+entry)");
+    }
+    else {
+        writeFileSync(giPath, toAdd.map((l) => `${l.comment}\n${l.line}`).join("\n\n") + "\n");
+        created.push(".gitignore");
+    }
+    return { created, skipped };
+}
+function reportInit(root, created, skipped) {
+    console.log(c.bold(c.cyan("\n  RepoOS initialized")) + c.dim(`  ·  ${root}\n`));
+    for (const f of created)
+        console.log("  " + c.green("created ") + f);
+    for (const f of skipped)
+        console.log("  " + c.dim("exists  " + f));
+}
+/**
+ * The marker that identifies a RepoOS project root: repoos.toml. It lives at
+ * the root in BOTH layouts (root and repoos/ namespace), so this alone is a
+ * reliable, unambiguous signal. We deliberately do NOT scan for work/ dirs —
+ * a `repoos/work/` folder could just be the actual repoos repo clone (or any
+ * unrelated `work/`), which would make sibling directories false-positive as
+ * "already a RepoOS project".
+ */
+function repoOSMarker(dir) {
+    const p = join(dir, "repoos.toml");
+    return existsSync(p) ? p : null;
+}
+/** Nearest ancestor (or the dir itself) that already has a RepoOS layout. */
+function findRepoOSDir(start) {
+    let dir = resolve(start);
+    while (true) {
+        if (repoOSMarker(dir))
+            return dir;
+        const parent = resolve(dir, "..");
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function warnAlreadySetUp(dir, hint) {
+    console.log(c.yellow("\n  RepoOS is already set up in ") + c.cyan(dir) + c.yellow("."));
+    if (hint)
+        console.log(c.dim(`  ${hint}`));
+    const marker = repoOSMarker(dir);
+    if (marker) {
+        console.log(c.dim("  Detected because ") + c.cyan(marker) + c.dim(" exists."));
+    }
+    console.log(c.dim("  To initialize a brand-new project, run repoos init in a different (empty) directory."));
+}
+async function ask(question) {
+    const rl = createInterface({ input, output });
+    try {
+        const answer = await rl.question(question);
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+async function confirm(question, dflt) {
+    const hint = dflt ? " [Y/n]" : " [y/N]";
+    const answer = (await ask(question + c.dim(hint) + " ")).toLowerCase();
+    if (answer === "")
+        return dflt;
+    return answer === "y" || answer === "yes";
+}
+/** Ask where the scaffold should live: repo root (default) or a repoos/ subfolder. */
+async function askLayout() {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const answer = (await ask("  Where should RepoOS live?" +
+            c.dim("  r = repo root (default), n = repoos/ subfolder — avoids clashing with existing dirs") +
+            ": ")).toLowerCase();
+        if (answer === "" || answer === "r" || answer === "root")
+            return "root";
+        if (answer === "n" || answer === "namespace" || answer === "repoos")
+            return "repoos";
+        console.log(c.yellow(`  "${answer}" — type r (root) or n (repoos/ subfolder).`));
+    }
+    return "root";
+}
+/** Open a URL in the default browser. Fail-soft (best effort, never blocks). */
+function openBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? ["open", url]
+        : process.platform === "win32"
+            ? ["cmd", "/c", "start", "", url]
+            : ["xdg-open", url];
+    try {
+        const child = spawn(cmd[0], cmd.slice(1), {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        /* fail-soft */
+    }
+}
+function probePort(port) {
+    return new Promise((resolve) => {
+        const srv = createServer();
+        srv.once("error", () => resolve(false));
+        srv.listen(port, "127.0.0.1", () => srv.close(() => resolve(true)));
+    });
+}
+/** First free port at or above `start` (bounded). Falls back to `start`. */
+async function nextFreePort(start) {
+    for (let p = start; p < start + 50; p++) {
+        if (await probePort(p))
+            return p;
+    }
+    return start;
+}
+/**
+ * Ask for a serve port, defaulting to this repo's stable derived port (the same
+ * one `repoos serve` would pick). `explicit` is true only when the user typed a
+ * concrete port — the caller then pins it in repoos.toml so future `serve`s
+ * reuse it.
+ */
+async function askPort(derived) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const raw = await ask("  Preferred port" +
+            c.dim(` [${derived}] — Enter for this repo's default, 0 = let the OS pick a free port`) +
+            ": ");
+        if (raw === "")
+            return { port: derived, explicit: false };
+        const n = Number(raw);
+        if (Number.isInteger(n) && n >= 0 && n <= 65535) {
+            return { port: n, explicit: n > 0 };
+        }
+        console.log(c.yellow(`  "${raw}" isn't a valid port.`));
+    }
+    return { port: derived, explicit: false };
+}
+/** Pin `servePort` in repoos.toml so future `repoos serve` runs reuse it. */
+function persistServePort(root, port) {
+    const tomlPath = join(root, "repoos.toml");
+    try {
+        const text = readFileSync(tomlPath, "utf8");
+        if (/^\s*servePort\s*=/m.test(text))
+            return;
+        const line = `servePort = ${port}\n`;
+        const anchor = /^defaultAssignee\s*=.*$/m;
+        const next = anchor.test(text)
+            ? text.replace(anchor, (m) => `${m}\nservePort = ${port}`)
+            : text + (text.endsWith("\n") ? "" : "\n") + line;
+        writeFileSync(tomlPath, next);
+        console.log("  " + c.green("saved") + c.dim(` servePort = ${port} to repoos.toml`));
+    }
+    catch {
+        /* fail-soft — the server still starts on the chosen port this run */
+    }
+}
+async function guidedNewRepo(args) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error(c.red("\n  This directory isn't a git repo, so repoos init needs interactive prompts."));
+        console.error(c.dim("  Run it in a terminal, or run `git init` first and then `repoos init` again."));
+        process.exitCode = 1;
+        return;
+    }
+    const cwd = process.cwd();
+    let projectName = (args[0] ?? "").trim();
+    if (projectName && !/^[A-Za-z0-9._-]+$/.test(projectName)) {
+        console.error(c.red(`  Invalid project name "${projectName}" — use letters, digits, . _ -`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(c.dim("\n  Not inside a git repository."));
+    console.log(c.cyan("  repoos init will create a new RepoOS project here."));
+    console.log(c.dim("  Default: the CURRENT directory. Enter a project name to use a subdirectory instead."));
+    if (!projectName) {
+        projectName = await ask("  Project name" + c.dim(" (Enter = current directory)") + ": ");
+    }
+    let target = cwd;
+    if (projectName) {
+        target = join(cwd, projectName);
+        if (repoOSMarker(target)) {
+            warnAlreadySetUp(target, "Nothing to create — that project already exists.");
+            process.exitCode = 1;
+            return;
+        }
+        console.log();
+        const ok = await confirm("  Create the project in a new subdirectory " +
+            c.cyan(`./${projectName}`) +
+            c.dim(`  →  ${target}`), true);
+        if (!ok) {
+            console.log(c.yellow("\n  Cancelled — nothing was created."));
+            return;
+        }
+    }
+    else {
+        console.log(c.dim(`  →  Using the current directory: ${cwd}`));
+    }
+    const layout = await askLayout();
+    console.log();
+    const scaffoldFiles = layout === "repoos"
+        ? "repoos/work/, repoos/docs/, AGENTS.md, repoos.toml, .gitignore"
+        : "work/, docs/, AGENTS.md, repoos.toml, .gitignore";
+    const proceed = await confirm("  Ready to " +
+        c.cyan("git init") +
+        c.dim(" and scaffold " + scaffoldFiles) +
+        " in " +
+        c.cyan(target), true);
+    if (!proceed) {
+        console.log(c.yellow("\n  Cancelled — nothing was created."));
+        return;
+    }
+    const description = await ask("  Project description" +
+        c.dim(" — one line, gives the AI context to suggest next steps (optional, Enter to skip)") +
+        ": ");
+    if (!existsSync(target))
+        mkdirSync(target, { recursive: true });
+    // git health warnings — fail-soft, scaffold regardless
+    const gitOk = gitAvailable(target);
+    if (!gitOk) {
+        console.log(c.yellow("\n  Warning: git doesn't appear to be installed — scaffolding without git."));
+    }
+    else if (!gitConfig(target, "user.name") && !gitConfig(target, "user.email")) {
+        console.log(c.yellow("\n  Warning: no git identity is configured."));
+        console.log(c.dim("    git may auto-detect it, or the initial commit may fail. Set it with:"));
+        console.log(c.dim('    git config --global user.name "You" && git config --global user.email you@example.com'));
+    }
+    const { created, skipped } = scaffoldInto(target, description, layout);
+    reportInit(target, created, skipped);
+    if (!gitOk) {
+        console.log(c.dim("  To add git later: git init && git add -A && git commit"));
+    }
+    else if (gitInit(target)) {
+        console.log("  " + c.green("git init") + c.dim("  ok"));
+    }
+    else {
+        console.log(c.yellow("  Warning: git init failed — files left uncommitted."));
+    }
+    if (gitOk && (await confirm("\n  Make an initial commit of the scaffold?", true))) {
+        const hash = gitCommitAll(target, INITIAL_COMMIT_MSG);
+        if (hash) {
+            console.log("  " + c.green("committed ") + c.dim(hash));
+        }
+        else {
+            console.log(c.yellow("  Warning: initial commit failed (unconfigured identity or a hook) — files left uncommitted."));
+        }
+    }
+    if (await confirm("\n  Launch the RepoOS web console now to start building?", true)) {
+        const { port: preferred, explicit } = await askPort(deriveServePort(target));
+        let port = preferred;
+        if (preferred > 0) {
+            const free = await nextFreePort(preferred);
+            if (free !== preferred) {
+                console.log(c.yellow(`  Port ${preferred} is in use — using ${free} instead.`));
+                port = free;
+            }
+        }
+        // Only pin an explicitly chosen port. The derived default is already stable
+        // per checkout, so writing it would just add noise to repoos.toml.
+        if (explicit)
+            persistServePort(target, preferred);
+        const dirHint = target === cwd ? null : `cd ${target}`;
+        if (target !== cwd)
+            process.chdir(target);
+        // A child process can change ITS OWN cwd (above) but never the parent
+        // shell's — the user's terminal is still sitting in `cwd`. Print the
+        // exact commands to run rather than just noting the mismatch, so there's
+        // nothing to figure out once this server is stopped.
+        if (dirHint) {
+            console.log(c.dim("\n  Your shell is still in ") +
+                c.cyan(cwd) +
+                c.dim(". When you come back to this project, run:\n\n") +
+                "    " +
+                c.cyan(dirHint) +
+                "\n    " +
+                c.cyan("repoos serve") +
+                "\n");
+        }
+        console.log(c.dim("  Starting the RepoOS web console…"));
+        // Opening the browser is deferred to onReady — the server isn't actually
+        // listening until cmdServe's startServer() resolves, and opening a tab
+        // any earlier races that startup, showing connection errors until a
+        // manual reload.
+        await cmdServe(["--port", String(port)], {
+            onReady: (url) => openBrowser(url),
+            onShutdown: dirHint
+                ? () => console.log(c.dim("  Start it again with:\n\n    ") +
+                    c.cyan(dirHint) +
+                    "\n    " +
+                    c.cyan("repoos serve") +
+                    "\n")
+                : undefined,
+        });
+        return;
+    }
+    const dirHint = target === cwd ? "" : `cd ${target}  ·  `;
+    console.log("\n  Next: " +
+        c.cyan(dirHint + "repoos list") +
+        c.dim("  ·  ") +
+        c.cyan("repoos show 0001") +
+        c.dim("  ·  ") +
+        c.cyan('repoos new "My task"') +
+        c.dim("  ·  ") +
+        c.cyan("repoos serve") +
+        c.dim(" to open the web console") +
+        "\n");
+}
+export async function cmdInit(args) {
+    const cwd = process.cwd();
+    if (isGitRepo(cwd)) {
+        // existing-repo path — unchanged, idempotent, no prompts
+        const root = findRepoRoot(cwd);
+        const { created, skipped } = scaffoldInto(root, "", "root", "existing");
+        if (created.length === 0) {
+            warnAlreadySetUp(root, "Nothing to initialize here.");
+            for (const f of skipped)
+                console.log("  " + c.dim("exists  " + f));
+            return;
+        }
+        reportInit(root, created, skipped);
+        return;
+    }
+    const alreadyHere = findRepoOSDir(cwd);
+    if (alreadyHere) {
+        warnAlreadySetUp(alreadyHere, "This directory isn't a git repo, but it sits inside an existing RepoOS setup.");
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        await guidedNewRepo(args);
+    }
+    catch {
+        console.log(c.yellow("\n  Cancelled."));
+    }
+}