@cmnwlth/cli 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kristof Feys
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/dist/index.d.ts

@@ -0,0 +1,442 @@
+import { NewNoteInput } from '@cmnwlth/core';
+
+/** Per-source counts of what seeding mined from the repo. */
+interface InitBySource {
+    adr: number;
+    git: number;
+    config: number;
+}
+/** Flags that shape an `init` run, parsed from the CLI. */
+interface InitOptions {
+    /** Explicit brain directory to create/use instead of {@link defaultBrainDir}. */
+    brain?: string;
+    /** Skip the confirmation prompt and seed non-interactively. */
+    yes?: boolean;
+    /** Re-run seeding even if this project already resolves to a brain (skip JOIN). */
+    reseed?: boolean;
+    /** Gather + stage seed candidates. Defaults to `true`; `false` creates the brain but skips staging. */
+    seed?: boolean;
+}
+/**
+ * Injected side effects so {@link runInit} is deterministic and unit-testable without
+ * touching the filesystem, spawning `commonwealth-curate`, or prompting a human.
+ */
+interface InitDeps {
+    /** Mine cold-start candidates from the repo (usually `@cmnwlth/seed`'s `gatherCandidates`). */
+    gather(repoDir: string): Promise<{
+        candidates: NewNoteInput[];
+        bySource: InitBySource;
+    }>;
+    /** Resolve the brain this project already belongs to, or `null` if none. */
+    resolveBrain(cwd: string): Promise<string | null>;
+    /** Scaffold a fresh brain at `dir` with the given human-readable name. */
+    createBrain(dir: string, name: string): Promise<void>;
+    /**
+     * Record that `repoDir` maps to `brainDir` in the global brain registry (ADR-0011). The
+     * registry is the default source of truth; the per-project `.commonwealth/brain` marker
+     * remains an optional manual override (`core.setBrainMarker`), not written here.
+     */
+    registerBrain(repoDir: string, brainDir: string): Promise<void>;
+    /** Stage candidates into the brain's review queue; returns how many were captured. */
+    stage(brainDir: string, candidates: NewNoteInput[]): Promise<{
+        captured: number;
+    }>;
+    /** Ask the user a yes/no question; resolves to their answer. */
+    confirm(message: string): Promise<boolean>;
+    /** Emit a human-facing line (diagnostics stream, never stdout data). */
+    log(message: string): void;
+}
+/** What an {@link runInit} run did, for the CLI to summarize and tests to assert on. */
+interface InitResult {
+    /** `new` = brain created + seeded; `join` = mounted existing brain; `skipped` = created but seeding declined. */
+    mode: "new" | "join" | "skipped";
+    /** The brain directory this project is now pinned to. */
+    brainDir: string;
+    /** How many candidate notes were staged into the review queue. */
+    staged: number;
+    /** How many candidates seeding gathered (0 in JOIN mode). */
+    gathered: number;
+}
+/**
+ * Walk up from `startDir` looking for a `.git` directory; return the repo root, or fall
+ * back to `startDir` when no `.git` ancestor exists (e.g. a not-yet-initialized project).
+ *
+ * @param startDir Directory to start the upward search from.
+ * @returns The nearest ancestor containing `.git`, else `startDir`.
+ */
+declare function findRepoRoot(startDir: string): string;
+/**
+ * Compute the default brain directory for a project. The brain is a SEPARATE repo living
+ * under `~/.commonwealth/brains/<basename>-<hash>`, never nested inside the project itself.
+ * The short hash of the FULL resolved path disambiguates same-named projects in different
+ * locations (`~/work/app` vs `~/personal/app`), which would otherwise collapse to one brain
+ * and silently share it (#103). Deterministic, so re-running `init` maps to the same brain.
+ *
+ * @param repoRoot The project's repo root.
+ * @returns An absolute path for the project's default brain.
+ */
+declare function defaultBrainDir(repoRoot: string): string;
+/**
+ * Orchestrate `commonwealth init`. Deterministic and side-effect-free except through `deps`.
+ *
+ * Flow: resolve the repo root and any existing brain. If one exists and we're not
+ * reseeding, JOIN it (register the mapping, done). Otherwise create a new brain, register
+ * the project → brain mapping, gather seed candidates, preview them, and — guarded behind
+ * confirmation unless `--yes` — stage them into the review queue. Brain creation and the
+ * registry mapping are idempotent and always run; every content write (staging) is gated
+ * by `confirm`.
+ *
+ * @param cwd The directory `commonwealth init` was invoked from.
+ * @param opts Parsed CLI flags.
+ * @param deps Injected side effects.
+ * @returns A structured summary of what happened.
+ */
+declare function runInit(cwd: string, opts: InitOptions, deps: InitDeps): Promise<InitResult>;
+
+/**
+ * A minimal interactive prompter over a terminal. {@link createReadlinePrompter} wires this to
+ * `node:readline/promises`; the wizard depends only on this interface so tests can drive it with a
+ * scripted fake and never touch a real TTY.
+ */
+interface Prompter {
+    /** Ask for free text; show `message [def]: `; empty input returns `def`. */
+    text(message: string, def: string): Promise<string>;
+    /** Ask a yes/no question defaulting to `def`; empty input returns `def`. */
+    confirm(message: string, def: boolean): Promise<boolean>;
+    /**
+     * Numbered multi-select over the given items. Prints each with a `[x]`/`[ ]` marker reflecting
+     * `defaultSelected`, then accepts `all` / `none` / a comma-or-space list of 1-based indices;
+     * empty input keeps the defaults. Returns the chosen items' `value`s (in item order).
+     */
+    select(message: string, items: {
+        label: string;
+        value: string;
+    }[], defaultSelected: boolean[]): Promise<string[]>;
+    /** Release the underlying readline interface (idempotent). */
+    close(): void;
+}
+/**
+ * True only when BOTH stdin and stdout are TTYs — the precondition for interactive prompting.
+ * Non-TTY (piped/CI) callers must fall back to defaults + flags and never block on stdin.
+ */
+declare function isInteractive(): boolean;
+/**
+ * Parse a yes/no answer. Recognizes `y`/`yes`/`n`/`no` case-insensitively (trimmed); empty input
+ * returns `def`; anything else also falls back to `def` (a lenient default-accept). Pure, so it is
+ * unit-testable without a TTY.
+ *
+ * @param input Raw line the user typed.
+ * @param def The default applied to empty (or unrecognized) input.
+ * @returns The resolved boolean answer.
+ */
+declare function parseConfirm(input: string, def: boolean): boolean;
+/**
+ * Resolve a free-text answer against its default: empty (trimmed) input returns `def`, otherwise
+ * the trimmed input. Pure counterpart to {@link Prompter.text} for unit tests.
+ *
+ * @param input Raw line the user typed.
+ * @param def The default applied to empty input.
+ * @returns The resolved text answer.
+ */
+declare function parseText(input: string, def: string): string;
+/**
+ * Resolve a multi-select answer against a list of candidate values. Pure counterpart to
+ * {@link Prompter.select} so tests never touch a TTY. Rules:
+ * - empty (trimmed) input keeps `defaultSelected` (values whose flag is true, in order);
+ * - `all` selects every value; `none` selects nothing;
+ * - otherwise the input is split on commas/whitespace and each token parsed as a 1-based index;
+ *   out-of-range or non-numeric tokens are ignored, duplicates collapse, and the result is
+ *   returned in `values` order.
+ *
+ * @param input Raw line the user typed.
+ * @param values The candidate values, in display order.
+ * @param defaultSelected Per-value default flags (same length/order as `values`).
+ * @returns The chosen values, in `values` order.
+ */
+declare function parseSelection(input: string, values: string[], defaultSelected: boolean[]): string[];
+/**
+ * A real {@link Prompter} backed by `node:readline/promises` over stdin/stdout. Only construct this
+ * after {@link isInteractive} returns true; on a non-TTY it would block waiting for input.
+ *
+ * @returns A prompter whose `close()` ends the readline interface.
+ */
+declare function createReadlinePrompter(): Prompter;
+
+/**
+ * Flags that shape a full `commonwealth init` orchestration. The step gates (`seed`, `mcp`,
+ * `daemon`, `build`, `scope`) default to `true` when omitted; pass `false` to skip that step. This
+ * is a type alias (not an interface) so it stays free of empty-interface lint noise.
+ */
+type OnboardOptions = {
+    /** Explicit brain directory to create/use instead of the project default. */
+    brain?: string;
+    /** Skip the whole-plan confirmation and run non-interactively. */
+    yes?: boolean;
+    /** Re-run seeding even if this project already resolves to a brain. */
+    reseed?: boolean;
+    /** Gather + stage seed candidates. Default: true. `false` skips staging. */
+    seed?: boolean;
+    /**
+     * Install the Commonwealth plugin (global MCP + session hooks) via the repo marketplace.
+     * Default: true. The plugin resolves the brain per repo dynamically, so no brain dir is
+     * pinned. `mcp` is a backward-compatible alias for this gate.
+     */
+    plugin?: boolean;
+    /** Backward-compatible alias for {@link OnboardOptions.plugin}. */
+    mcp?: boolean;
+    /** Start the sync daemon for the brain. Default: true. */
+    daemon?: boolean;
+    /** Build/bundle the workspace if dist artifacts are missing. Default: true. */
+    build?: boolean;
+    /** Add the repo root to the capture allowlist (`scope allow`). Default: true. */
+    scope?: boolean;
+    /** Enable auto-ADR capture for the brain. Default: false. */
+    autoAdr?: boolean;
+    /** Add this URL as the brain's git `origin` remote. Default: undefined (skip). */
+    remote?: string;
+    /**
+     * Folders to sync into this brain: each is added to the capture allowlist and wired to the
+     * brain via the global user registry (plus a convenience symlink). Default: `[cwd]` (#61).
+     */
+    syncFolders?: string[];
+    /**
+     * Repos to mine (seed) into the brain now. Default: {@link OnboardOptions.syncFolders} when
+     * seeding is enabled, else `[]`.
+     */
+    seedRepos?: string[];
+};
+/**
+ * Injected side effects so {@link runOnboard} is deterministic and unit-testable without
+ * building the workspace, delegating to `runInit`, spawning `claude`, or starting a daemon.
+ */
+interface OnboardDeps {
+    /** Build the workspace when dist artifacts are missing; a no-op (with a note) otherwise. */
+    ensureBuilt(): Promise<{
+        built: boolean;
+        skipped?: string;
+    }>;
+    /** Create/seed/join the brain (delegates to `runInit` with real init deps). */
+    init(cwd: string, initOpts: InitOptions): Promise<InitResult>;
+    /** Idempotently add `folder` to the capture allowlist (`scope allow`; de-dupes). */
+    configureScope(folder: string): Promise<{
+        added: boolean;
+        skipped?: string;
+    }>;
+    /**
+     * Register `folder → brainDir` in the global user registry (the default brain-wiring source
+     * of truth) and drop a convenience `~/.commonwealth/brains/<name>` symlink. Idempotent;
+     * never throws. `mapped` reflects the registry write, `linked` the symlink; `skipped` carries
+     * a reason when the symlink could not be created (the mapping still counts).
+     */
+    registerBrain(folder: string, brainDir: string): Promise<{
+        mapped: boolean;
+        linked: boolean;
+        skipped?: string;
+    }>;
+    /** Mine `repoDir` and stage the candidates into `brainDir`'s review queue. */
+    seedFrom(brainDir: string, repoDir: string): Promise<{
+        staged: number;
+        skipped?: string;
+    }>;
+    /**
+     * Ensure the per-user scope config file exists (creating an empty one if missing) and return
+     * its resolved path. Called near the end of onboarding regardless of scope choices.
+     */
+    ensureUserConfig(): Promise<{
+        path: string;
+    }>;
+    /** Enable/disable auto-ADR capture for `brainDir`. */
+    setAutoAdr(brainDir: string, on: boolean): Promise<{
+        set: boolean;
+        skipped?: string;
+    }>;
+    /** Add `url` as the brain's git `origin` remote unless one already exists. */
+    setRemote(brainDir: string, url: string): Promise<{
+        set: boolean;
+        skipped?: string;
+    }>;
+    /**
+     * Idempotently install the Commonwealth plugin (global MCP + session hooks) via the repo
+     * marketplace with the `claude` CLI. No brain dir is needed — the plugin + its SessionStart
+     * hook resolve the brain per repo dynamically (ADR-0012). Never throws. `installed` is true
+     * when the plugin is present after the step; `skipped` carries a reason when it is not.
+     */
+    installPlugin(): Promise<{
+        installed: boolean;
+        skipped?: string;
+    }>;
+    /** Start the sync daemon for `brainDir`, or report it already running. */
+    startDaemon(brainDir: string): Promise<{
+        started: boolean;
+        alreadyRunning?: boolean;
+        skipped?: string;
+    }>;
+    /** Ask the user a yes/no question; resolves to their answer. */
+    confirm(message: string): Promise<boolean>;
+    /** Emit a human-facing line (diagnostics stream, never stdout data). */
+    log(message: string): void;
+}
+/** What a {@link runOnboard} run did, for the CLI to summarize and tests to assert on. */
+interface OnboardResult {
+    /** The brain directory this project is now pinned to. */
+    brainDir: string;
+    /** Delegated `runInit` mode: `new` / `join` / `skipped`. */
+    mode: InitResult["mode"];
+    /** Whether {@link OnboardDeps.ensureBuilt} actually built anything. */
+    built: boolean;
+    /** How many candidate notes were staged into the review queue (summed across seeded repos). */
+    staged: number;
+    /** How many folders were added to the capture allowlist. */
+    scopedFolders: number;
+    /** How many folders were wired into a brain via the global registry. */
+    mappedFolders: number;
+    /** How many repos were seeded (mined) into the brain. */
+    seededRepos: number;
+    /** Resolved path of the per-user scope config file (always ensured to exist). */
+    scopeConfigPath: string;
+    /** Short allowlist status string (e.g. `added`, `skipped`). */
+    scope: string;
+    /** Short auto-ADR status string (e.g. `enabled`, `skipped`). */
+    autoAdr: string;
+    /** Short brain-remote status string (e.g. `set`, `origin exists`, `skipped`). */
+    remote: string;
+    /** Short plugin-install status string (e.g. `installed`, `skipped`). */
+    plugin: string;
+    /** Short daemon status string (e.g. `started`, `already running`, `skipped`). */
+    daemon: string;
+}
+/**
+ * Orchestrate the full `commonwealth init`: build the workspace (if needed), create/seed/join
+ * the brain, install the Commonwealth plugin (global MCP + session hooks), and start the sync
+ * daemon — a single idempotent command. Deterministic and side-effect-free except through `deps`.
+ *
+ * Flow: build a plan and log it; unless `--yes`, confirm the whole plan (a decline does NOTHING
+ * and returns early); then run each enabled step in order — ensureBuilt, init, installPlugin,
+ * startDaemon — and log a done summary. Each step is individually gated by its option and every
+ * step is idempotent, so re-running is safe.
+ *
+ * @param cwd The directory `commonwealth init` was invoked from.
+ * @param opts Parsed CLI flags (step gates default to enabled).
+ * @param deps Injected side effects.
+ * @returns A structured summary of what happened.
+ */
+declare function runOnboard(cwd: string, opts: OnboardOptions, deps: OnboardDeps): Promise<OnboardResult>;
+/** The answers a wizard collects, ready to be turned into {@link OnboardOptions}. */
+interface WizardAnswers {
+    brain: string;
+    scope: boolean;
+    seed: boolean;
+    plugin: boolean;
+    daemon: boolean;
+    autoAdr: boolean;
+    remote: string;
+}
+/** Defaults the wizard seeds its prompts with (Enter accepts each). */
+interface WizardDefaults {
+    brain: string;
+    /**
+     * The invocation dir — the fallback sync/seed target when no sibling repos are found, and the
+     * base whose parent is offered as the default scan directory. Deliberately NOT the git root:
+     * that can climb above `cwd` and over-scope (#61).
+     */
+    projectDir: string;
+    scope: boolean;
+    seed: boolean;
+    plugin: boolean;
+    daemon: boolean;
+    autoAdr: boolean;
+}
+/** What {@link runWizard} produces: the assembled options, or an abort signal. */
+type WizardOutcome = {
+    proceed: true;
+    opts: OnboardOptions;
+} | {
+    proceed: false;
+    opts: null;
+};
+/** Injectable side effects for {@link runWizard} (defaults to the real discovery). */
+interface WizardDeps {
+    /** Scan `baseDir` for git repositories (defaults to {@link findGitRepos}). */
+    scan(baseDir: string): Promise<string[]>;
+}
+/**
+ * Drive the interactive wizard: ask each choice with a sensible default (Enter accepts), then a
+ * final `Proceed?` confirm. Pure orchestration over a {@link Prompter} + {@link WizardDeps}, so
+ * tests script answers with a fake and never touch a real TTY or filesystem. A declined
+ * `Proceed?` returns `{ proceed: false }` and the caller must perform ZERO side effects.
+ *
+ * After the brain prompt it asks which directory to scan for projects, discovers the git repos
+ * beneath it, and lets the user multi-select which folders to SYNC into the brain and which repos
+ * to SEED now (seed defaults to the sync selection). When nothing is found it falls back to the
+ * repo root for both.
+ *
+ * The returned `opts` carry `yes: true` because the wizard has already confirmed — the caller must
+ * NOT prompt again inside {@link runOnboard}.
+ *
+ * @param defaults Per-prompt defaults (usually derived from environment probing).
+ * @param prompter The interactive prompter.
+ * @param deps Injectable discovery (defaults to scanning the real filesystem).
+ * @returns A {@link WizardOutcome}: the options to run, or an abort.
+ */
+declare function runWizard(defaults: WizardDefaults, prompter: Prompter, deps?: WizardDeps): Promise<WizardOutcome>;
+
+/** Options for {@link defaultInitDeps}, mostly to make wiring testable/overridable. */
+interface DefaultInitDepsOptions {
+    /** Absolute path to `commonwealth-curate`'s built entry (its `capture` subcommand is spawned). */
+    curateEntry?: string;
+    /** When true, `confirm` always resolves `true` (from `--yes`). */
+    assumeYes?: boolean;
+}
+/**
+ * Wire the real {@link InitDeps}: seed for gathering, core for brain/marker resolution, a
+ * spawned `commonwealth-curate capture` for staging, a readline prompt for confirmation, and
+ * stderr for logging. Pure orchestration lives in {@link runInit}; this is the only place
+ * that performs real I/O.
+ *
+ * @param opts Optional overrides ({@link DefaultInitDepsOptions}).
+ * @returns A fully-wired {@link InitDeps}.
+ */
+declare function defaultInitDeps(opts?: DefaultInitDepsOptions): InitDeps;
+/** Options for {@link defaultOnboardDeps}, mostly to make wiring testable/overridable. */
+interface DefaultOnboardDepsOptions {
+    /** Repo root to resolve dist paths from; defaults to the nearest `.git` ancestor of cwd. */
+    repoRoot?: string;
+    /** Absolute path to `commonwealth-curate`'s built entry, forwarded to {@link defaultInitDeps}. */
+    curateEntry?: string;
+}
+declare function defaultOnboardDeps(opts?: DefaultOnboardDepsOptions): OnboardDeps;
+
+/** Options for {@link findGitRepos}. */
+interface FindGitReposOptions {
+    /** How many directory levels below `baseDir` to descend (default 2). `0` = only `baseDir`. */
+    maxDepth?: number;
+}
+/**
+ * Discover git repositories under `baseDir`: every directory that directly contains a `.git`
+ * entry (a file or directory), scanning up to `maxDepth` levels deep. Skips `node_modules` and
+ * any dot-directory (e.g. `.git`, `.cache`) so it never descends into vendored or hidden trees.
+ *
+ * Never throws: an unreadable directory is simply skipped. Results are absolute, de-duped, and
+ * sorted lexicographically for deterministic output.
+ *
+ * @param baseDir Directory to scan from.
+ * @param opts Optional depth cap ({@link FindGitReposOptions}).
+ * @returns Absolute paths of directories that are git repos, sorted and de-duped.
+ */
+declare function findGitRepos(baseDir: string, opts?: FindGitReposOptions): Promise<string[]>;
+
+/**
+ * `commonwealth` CLI entry. Parses argv, dispatches `init` to the full {@link runOnboard}
+ * orchestration, prints the plan + a one-line summary to stderr, and resolves the exit code.
+ * Diagnostics go to stderr; there is no stdout data contract for `init`. Unknown commands and
+ * `--help` print usage.
+ *
+ * `parseArgs` has no native boolean negation, so `--no-seed`/`--no-mcp`/`--no-daemon`/`--no-build`
+ * are stripped from argv here and turned into `false` gates before parsing the rest.
+ *
+ * @param argv Arguments after `node <script>` (i.e. `process.argv.slice(2)`).
+ * @returns Exit code: 0 on success, 2 on usage error.
+ */
+declare function run(argv: string[]): Promise<number>;
+
+export { type FindGitReposOptions, type InitBySource, type InitDeps, type InitOptions, type InitResult, type OnboardDeps, type OnboardOptions, type OnboardResult, type Prompter, type WizardAnswers, type WizardDefaults, type WizardDeps, type WizardOutcome, createReadlinePrompter, defaultBrainDir, defaultInitDeps, defaultOnboardDeps, findGitRepos, findRepoRoot, isInteractive, parseConfirm, parseSelection, parseText, run, runInit, runOnboard, runWizard };