@monte3l/groundwork 0.1.0-next.0 → 1.0.0-rc.2

package/README.md

@@ -7,10 +7,10 @@ existing project and writes only a report (**adopt** mode, which never touches a
 project file).
 
 ```bash
-# 0.x is a prerelease and ships on the `next` dist-tag
-npx @monte3l/groundwork@next my-new-project
-npx @monte3l/groundwork@next my-new-project --pack statusline
-npx @monte3l/groundwork@next ../existing-project
+# currently a 1.0.0 release candidate, shipping on the `rc` dist-tag
+npx @monte3l/groundwork@rc my-new-project
+npx @monte3l/groundwork@rc my-new-project --pack statusline
+npx @monte3l/groundwork@rc ../existing-project
 ```
 
 Requires Node 24+. No prompts, and no network call beyond the `pnpm install` a

package/bin/m3l-groundwork.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import process from "node:process";
-import { main } from "../dist/main.js";
+import { main, CliUsageError } from "../dist/main.js";
 
 try {
   main(process.argv.slice(2));
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));
-  process.exitCode = 1;
+  process.exitCode = error instanceof CliUsageError ? 2 : 1;
 }

package/dist/harness/rules.js

@@ -26,6 +26,7 @@ export const CURRENT_MODELS = [
     "haiku",
     "fable",
     "claude-opus-5",
+    "claude-opus-5-5",
     "claude-sonnet-5",
     "claude-fable-5-1",
     "claude-haiku-4-5",

package/dist/main.d.ts

@@ -11,6 +11,21 @@ export interface CliOptions {
     listPacks: boolean;
     packs: string[];
 }
+/**
+ * Thrown for a bad invocation (unknown flag, missing target dir, missing flag
+ * value, contradictory mode flags) -- distinguished from a runtime error so the
+ * CLI exits 2, not 1.
+ *
+ * @example
+ * ```sh
+ * npx @monte3l/groundwork@next ./my-app --bogus
+ * # stderr: unrecognized option: --bogus (followed by the usage text)
+ * echo $? # 2 -- a runtime failure exits 1 instead
+ * ```
+ */
+export declare class CliUsageError extends Error {
+    readonly name = "CliUsageError";
+}
 /** Parses argv into structured options. Throws with USAGE on a missing target dir, unless --help/--version/--list-packs is present. */
 export declare function parseArgs(argv: string[]): CliOptions;
 /** Resolves `templates/core` for a source checkout or a published tarball -- see `assets.ts`. */

package/dist/main.js

@@ -37,8 +37,8 @@ const USAGE = [
     "  --fresh                 Force fresh-bootstrap mode, even if the target looks pre-existing",
     "  --pack <name>           Install an opt-in pack from templates/packs/ (fresh mode only; repeatable)",
     "  --list-packs            Print every available pack and exit",
-    "  --help                  Print this message",
-    "  --version               Print the CLI's version",
+    "  --help, -h              Print this message",
+    "  --version, -v           Print the CLI's version",
     "",
     "With no --adopt/--fresh override, the target directory is inspected: an",
     "empty or missing directory bootstraps fresh; a directory that already",
@@ -56,6 +56,30 @@ const REPEATABLE_VALUE_FLAGS = new Set(["--pack"]);
 const HELP_FLAGS = new Set(["--help", "-h"]);
 const VERSION_FLAGS = new Set(["--version", "-v"]);
 const LIST_PACKS_FLAGS = new Set(["--list-packs"]);
+const BOOLEAN_FLAGS = new Set([
+    "--skip-install",
+    "--force",
+    "--adopt",
+    "--fresh",
+    ...LIST_PACKS_FLAGS,
+    ...HELP_FLAGS,
+    ...VERSION_FLAGS,
+]);
+/**
+ * Thrown for a bad invocation (unknown flag, missing target dir, missing flag
+ * value, contradictory mode flags) -- distinguished from a runtime error so the
+ * CLI exits 2, not 1.
+ *
+ * @example
+ * ```sh
+ * npx @monte3l/groundwork@next ./my-app --bogus
+ * # stderr: unrecognized option: --bogus (followed by the usage text)
+ * echo $? # 2 -- a runtime failure exits 1 instead
+ * ```
+ */
+export class CliUsageError extends Error {
+    name = "CliUsageError";
+}
 /** Splits argv into positionals, boolean flags, and value-flag pairs -- a value-flag's value is never mistaken for a positional. */
 function tokenizeArgv(argv) {
     const positional = [];
@@ -72,22 +96,27 @@ function tokenizeArgv(argv) {
         }
         if (REPEATABLE_VALUE_FLAGS.has(arg)) {
             const value = argv[i + 1];
-            if (value !== undefined) {
-                const existing = repeatableValues.get(arg) ?? [];
-                existing.push(value);
-                repeatableValues.set(arg, existing);
-                i++;
+            if (value === undefined || value.startsWith("-")) {
+                throw new CliUsageError(`${arg} requires a value\n\n${USAGE}`);
             }
+            const existing = repeatableValues.get(arg) ?? [];
+            existing.push(value);
+            repeatableValues.set(arg, existing);
+            i++;
             continue;
         }
         if (VALUE_FLAGS.has(arg)) {
             const value = argv[i + 1];
-            if (value !== undefined) {
-                values.set(arg, value);
-                i++;
+            if (value === undefined || value.startsWith("-")) {
+                throw new CliUsageError(`${arg} requires a value\n\n${USAGE}`);
             }
+            values.set(arg, value);
+            i++;
             continue;
         }
+        if (!BOOLEAN_FLAGS.has(arg)) {
+            throw new CliUsageError(`unrecognized option: ${arg}\n\n${USAGE}`);
+        }
         flags.add(arg);
     }
     return { positional, flags, values, repeatableValues };
@@ -112,9 +141,15 @@ export function parseArgs(argv) {
             packs: [],
         };
     }
+    if (flags.has("--adopt") && flags.has("--fresh")) {
+        throw new CliUsageError(`--adopt and --fresh are mutually exclusive\n\n${USAGE}`);
+    }
     const targetArg = positional[0];
     if (targetArg === undefined) {
-        throw new Error(USAGE);
+        throw new CliUsageError(USAGE);
+    }
+    if (positional.length > 1) {
+        throw new CliUsageError(`unexpected argument(s): ${positional.slice(1).join(" ")}\n\n${USAGE}`);
     }
     const targetDir = resolve(targetArg);
     const explicitName = values.get("--name");

package/dist/report.js

@@ -280,7 +280,7 @@ export function renderReport(inventory) {
     const sections = [
         "# Adoption report",
         "",
-        `Generated ${inventory.generatedAt} by m3l-groundwork ${inventory.cliVersion}.`,
+        `Generated ${inventory.generatedAt} by m3l-groundwork ${inventory.cliVersion} (inventory schema ${inventory.schemaVersion}).`,
         "",
         `**Mode:** adopt -- ${inventory.modeSignal}`,
         "",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@monte3l/groundwork",
-  "version": "0.1.0-next.0",
-  "description": "Deterministic Phase A bootstrapper: writes the m3l-groundwork baseline (toolchain + Claude Code harness) into a new directory, or surveys an existing project read-only. No prompts, no network beyond the package install.",
+  "version": "1.0.0-rc.2",
+  "description": "Deterministic bootstrapper: writes the m3l-groundwork baseline (toolchain + Claude Code harness) into a new directory, or surveys an existing project read-only. No prompts, no network beyond the package install.",
   "keywords": [
     "typescript",
     "claude-code",
@@ -27,13 +27,7 @@
   "bin": {
     "m3l-groundwork": "bin/m3l-groundwork.mjs"
   },
-  "main": "./dist/main.js",
-  "types": "./dist/main.d.ts",
   "exports": {
-    ".": {
-      "types": "./dist/main.d.ts",
-      "import": "./dist/main.js"
-    },
     "./package.json": "./package.json"
   },
   "files": [

package/templates/core/bin/lib/harness-rules.mjs

@@ -27,6 +27,7 @@ export const CURRENT_MODELS = [
   "haiku",
   "fable",
   "claude-opus-5",
+  "claude-opus-5-5",
   "claude-sonnet-5",
   "claude-fable-5-1",
   "claude-haiku-4-5",