@growthub/create-growthub-local 0.2.2 → 0.2.4

package/README.md

@@ -2,46 +2,72 @@
 
 `create-growthub-local` is the guided installer for Growthub Local.
 
+It now handles three lanes in one command, so a fresh user can get either the
+Paperclip Local App or a Custom Workspace Starter workspace in a single step —
+no second `growthub starter init` call required.
+
 ## Quickstart
 
 ```bash
-# Interactive (recommended)
+# Interactive discovery hub (kits / templates / workflows / agent harness / settings)
 npm create growthub-local@latest
 
-# Direct profile install
+# Paperclip Local App profiles
 npm create growthub-local@latest -- --profile gtm
 npm create growthub-local@latest -- --profile dx
+
+# Custom Workspace Starter (zero second step — scaffolds + registers as a fork)
+npm create growthub-local@latest -- --profile workspace --out ./my-workspace
 ```
 
 ## Installer Paths
 
-- **Profile mode** (`--profile gtm|dx`)
-  - runs direct onboarding for the selected local app profile
+- **Paperclip Local App** (`--profile gtm|dx`)
+  - runs `growthub onboard --yes` for the selected surface profile
+- **Custom Workspace Starter** (`--profile workspace`)
+  - runs `growthub starter init --out <path>` against the bundled
+    `growthub-custom-workspace-starter-v1` kit
+  - composes the already-shipping primitives — `copyBundledKitSource`,
+    `registerKitFork`, `writeKitForkPolicy`, `appendKitForkTraceEvent`,
+    and (optionally) `createFork` via the first-party GitHub integration
+  - no cross-package coupling beyond the existing `@growthub/cli` dep pin
 - **Discovery mode** (no profile)
-  - opens `growthub discover` so users can choose:
-    - Agent Harness
-    - Worker Kits
-    - Templates
+  - opens `growthub discover` so users can pick Worker Kits, Templates,
+    Workflows, Local Intelligence, Agent Harness, Settings, or Help
 
 ## Options
 
-| Flag | Description |
-|---|---|
-| `--profile gtm\|dx` | Optional direct install path for local app profiles |
-| `--run` | Start local runtime immediately after onboarding |
-| `--data-dir <path>` | Override install directory (default: `./growthub-local`) |
-| `--config <path>` | Use a custom config path |
-
-## After Install
+| Flag | Applies to | Description |
+|---|---|---|
+| `--profile gtm\|dx\|workspace` | all | Pick an install lane |
+| `--run` | `dx`, `gtm`, discovery | Start Growthub immediately after saving config |
+| `--data-dir <path>` | `dx`, `gtm`, discovery | Override install directory (default: `./growthub-local`) |
+| `--config <path>` | `dx`, `gtm`, discovery | Use a custom config path |
+| `--out <path>` | `workspace` | Destination directory for the new workspace |
+| `--kit <kit-id>` | `workspace` | Source kit id (default: `growthub-custom-workspace-starter-v1`) |
+| `--name <label>` | `workspace` | Human label for the fork |
+| `--upstream <owner/repo>` | `workspace` | When set, also creates a remote GitHub fork |
+| `--destination-org <org>` | `workspace` | Create the GitHub fork under an org |
+| `--fork-name <name>` | `workspace` | Override the GitHub fork name |
+| `--remote-sync-mode <mode>` | `workspace` | Initial `policy.remoteSyncMode` — `off` (default), `branch`, `pr` |
+| `--json` | `workspace` | Emit machine-readable output from `growthub starter init` |
+
+## After install — Paperclip Local App
 
 ```bash
 cd growthub-local
 npx growthub run
 ```
 
-Open CLI discovery again:
+## After install — Custom Workspace Starter
 
 ```bash
+cd my-workspace
+
+# Inspect your new fork (registration + policy + trace)
+npx growthub kit fork status <fork-id>
+
+# Re-open the discovery hub any time
 npx growthub
 ```
 

package/bin/create-growthub-local.mjs

@@ -9,50 +9,157 @@ import { fileURLToPath } from "node:url";
 const require = createRequire(import.meta.url);
 const __filename = fileURLToPath(import.meta.url);
 
+const VALID_PROFILES = new Set(["dx", "gtm", "workspace"]);
+const VALID_REMOTE_SYNC_MODES = new Set(["off", "branch", "pr"]);
+
 function printUsage() {
-  console.log("Usage: create-growthub-local [--profile <dx|gtm>] [--run] [--data-dir <path>] [--config <path>]");
+  console.log(
+    [
+      "Usage:",
+      "  create-growthub-local [--profile <dx|gtm|workspace>] [--out <path>]",
+      "                        [--data-dir <path>] [--config <path>]",
+      "                        [--run]",
+      "",
+      "Paperclip Local App profiles (dx | gtm):",
+      "  create-growthub-local --profile gtm",
+      "  create-growthub-local --profile dx --data-dir ./my-growthub",
+      "",
+      "Custom Workspace Starter profile (workspace):",
+      "  create-growthub-local --profile workspace --out ./my-workspace",
+      "  create-growthub-local --profile workspace --out ./my-workspace --name \"My Workspace\"",
+      "  create-growthub-local --profile workspace --out ./my-workspace \\",
+      "    --upstream Growthub-ai/growthub-custom-workspace-starter-v1 --remote-sync-mode off",
+      "",
+      "Discovery mode (no profile):",
+      "  create-growthub-local      # opens `growthub discover` picker",
+    ].join("\n"),
+  );
 }
 
 function parseArgs(argv) {
-  let profile = null;
-  let run = false;
-  let dataDir = null;
-  let config = null;
+  const opts = {
+    profile: null,
+    run: false,
+    dataDir: null,
+    config: null,
+    out: null,
+    kit: null,
+    name: null,
+    upstream: null,
+    destinationOrg: null,
+    forkName: null,
+    remoteSyncMode: null,
+    json: false,
+  };
 
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
+
     if (value === "--profile" && argv[index + 1]) {
-      profile = argv[index + 1];
+      opts.profile = String(argv[index + 1]).trim();
       index += 1;
       continue;
     }
     if (value === "--run") {
-      run = true;
+      opts.run = true;
       continue;
     }
     if ((value === "-d" || value === "--data-dir") && argv[index + 1]) {
-      dataDir = argv[index + 1];
+      opts.dataDir = argv[index + 1];
       index += 1;
       continue;
     }
     if ((value === "-c" || value === "--config") && argv[index + 1]) {
-      config = argv[index + 1];
+      opts.config = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--out" && argv[index + 1]) {
+      opts.out = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--kit" && argv[index + 1]) {
+      opts.kit = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--name" && argv[index + 1]) {
+      opts.name = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--upstream" && argv[index + 1]) {
+      opts.upstream = argv[index + 1];
       index += 1;
       continue;
     }
+    if (value === "--destination-org" && argv[index + 1]) {
+      opts.destinationOrg = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--fork-name" && argv[index + 1]) {
+      opts.forkName = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--remote-sync-mode" && argv[index + 1]) {
+      opts.remoteSyncMode = String(argv[index + 1]).trim();
+      index += 1;
+      continue;
+    }
+    if (value === "--json") {
+      opts.json = true;
+      continue;
+    }
     if (value === "-h" || value === "--help") {
       printUsage();
       process.exit(0);
     }
   }
 
-  if (profile !== null && profile !== "dx" && profile !== "gtm") {
+  if (opts.profile !== null && !VALID_PROFILES.has(opts.profile)) {
+    printUsage();
+    console.error(
+      `create-growthub-local only accepts --profile dx | gtm | workspace (got: ${opts.profile})`,
+    );
+    process.exit(1);
+  }
+
+  if (
+    opts.remoteSyncMode !== null
+    && !VALID_REMOTE_SYNC_MODES.has(opts.remoteSyncMode)
+  ) {
     printUsage();
-    console.error("create-growthub-local only accepts --profile dx or --profile gtm");
+    console.error(
+      `--remote-sync-mode must be one of off | branch | pr (got: ${opts.remoteSyncMode})`,
+    );
     process.exit(1);
   }
 
-  return { profile, run, dataDir, config };
+  const workspaceOnlyFlags = [
+    ["--out", opts.out],
+    ["--kit", opts.kit],
+    ["--name", opts.name],
+    ["--upstream", opts.upstream],
+    ["--destination-org", opts.destinationOrg],
+    ["--fork-name", opts.forkName],
+    ["--remote-sync-mode", opts.remoteSyncMode],
+  ];
+  if (opts.profile !== "workspace") {
+    for (const [flag, value] of workspaceOnlyFlags) {
+      if (value !== null) {
+        printUsage();
+        console.error(
+          `${flag} is only valid with --profile workspace (the Custom Workspace Starter path).`,
+        );
+        process.exit(1);
+      }
+    }
+  }
+
+  return opts;
 }
 
 function resolveGrowthubCliEntrypoint() {
@@ -78,10 +185,71 @@ function resolveGrowthubCliEntrypoint() {
   return path.resolve(cliPackageDir, growthubBin);
 }
 
-const { profile, run, dataDir, config } = parseArgs(process.argv.slice(2));
-const effectiveDataDir = dataDir ? path.resolve(process.cwd(), dataDir) : path.resolve(process.cwd(), "growthub-local");
-let growthubCli;
+function buildCliArgs(opts, effectiveDataDir, growthubCli) {
+  // --profile workspace → forward into `growthub starter init`
+  // (the Custom Workspace Starter surface, which composes
+  // copyBundledKitSource + registerKitFork + writeKitForkPolicy
+  // + appendKitForkTraceEvent and, optionally, createFork).
+  if (opts.profile === "workspace") {
+    const outArg = opts.out ?? "./my-workspace";
+    const absOut = path.resolve(process.cwd(), outArg);
+    const args = [growthubCli, "starter", "init", "--out", absOut];
+    if (opts.kit) args.push("--kit", opts.kit);
+    if (opts.name) args.push("--name", opts.name);
+    if (opts.upstream) args.push("--upstream", opts.upstream);
+    if (opts.destinationOrg) args.push("--destination-org", opts.destinationOrg);
+    if (opts.forkName) args.push("--fork-name", opts.forkName);
+    if (opts.remoteSyncMode) args.push("--remote-sync-mode", opts.remoteSyncMode);
+    if (opts.json) args.push("--json");
+    return args;
+  }
+
+  // --profile dx | gtm → existing Paperclip Local App onboarding flow.
+  if (opts.profile) {
+    return [
+      growthubCli,
+      "onboard",
+      "--yes",
+      ...(opts.run ? ["--run"] : []),
+      "--data-dir",
+      effectiveDataDir,
+      ...(opts.config ? ["--config", opts.config] : []),
+    ];
+  }
+
+  // No profile → open the shared discovery hub (kits / templates /
+  // workflows / agent harness / settings).
+  return [
+    growthubCli,
+    "discover",
+    ...(opts.run ? ["--run"] : []),
+    "--data-dir",
+    effectiveDataDir,
+    ...(opts.config ? ["--config", opts.config] : []),
+  ];
+}
 
+function buildCliEnv(opts) {
+  const env = {
+    ...process.env,
+    GROWTHUB_INSTALLER_MODE: "true",
+  };
+  // PAPERCLIP_SURFACE_PROFILE is only meaningful for the Paperclip
+  // Local App lanes (dx | gtm). The workspace profile scaffolds a
+  // Self-Healing Fork Sync workspace that has nothing to do with
+  // Paperclip surface selection, so we intentionally do not set it.
+  if (opts.profile === "dx" || opts.profile === "gtm") {
+    env.PAPERCLIP_SURFACE_PROFILE = opts.profile;
+  }
+  return env;
+}
+
+const opts = parseArgs(process.argv.slice(2));
+const effectiveDataDir = opts.dataDir
+  ? path.resolve(process.cwd(), opts.dataDir)
+  : path.resolve(process.cwd(), "growthub-local");
+
+let growthubCli;
 try {
   growthubCli = resolveGrowthubCliEntrypoint();
 } catch (error) {
@@ -93,35 +261,13 @@ try {
   process.exit(1);
 }
 
-const result = spawnSync(
-  process.execPath,
-  profile
-    ? [
-      growthubCli,
-      "onboard",
-      "--yes",
-      ...(run ? ["--run"] : []),
-      "--data-dir",
-      effectiveDataDir,
-      ...(config ? ["--config", config] : []),
-    ]
-    : [
-      growthubCli,
-      "discover",
-      ...(run ? ["--run"] : []),
-      "--data-dir",
-      effectiveDataDir,
-      ...(config ? ["--config", config] : []),
-    ],
-  {
-    cwd: process.cwd(),
-    stdio: "inherit",
-    env: {
-      ...process.env,
-      GROWTHUB_INSTALLER_MODE: "true",
-      ...(profile ? { PAPERCLIP_SURFACE_PROFILE: profile } : {}),
-    },
-  },
-);
+const cliArgs = buildCliArgs(opts, effectiveDataDir, growthubCli);
+const cliEnv = buildCliEnv(opts);
+
+const result = spawnSync(process.execPath, cliArgs, {
+  cwd: process.cwd(),
+  stdio: "inherit",
+  env: cliEnv,
+});
 
 process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growthub/create-growthub-local",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Growthub local installer for DX and GTM profiles",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@growthub/cli": "0.4.2"
+    "@growthub/cli": "0.5.0"
   },
   "keywords": [
     "growthub",