@emeryld/manager 0.5.0 → 0.6.0

package/README.md

@@ -1,15 +1,52 @@
 # @emeryld/manager
 
-Dev dependency built for Codex agents: scaffold RRRoutes packages, read the generated structure, and ship changes without rebuilding boilerplate. Install it in a pnpm workspace and call `pnpm manager-cli` from the workspace root.
+Dev dependency built for Codex agents: scan a pnpm workspace, scaffold RRRoutes packages, and ship releases without rebuilding boilerplate. Install it in a workspace and call `pnpm manager-cli` from the root to drive everything interactively or via arguments for headless automation.
 
-## Quick start (agents)
+## Quick start
 - Install: `pnpm add -D @emeryld/manager`
 - Add a script: `"manager-cli": "manager-cli"` in the workspace `package.json`
-- Discover templates fast: `pnpm manager-cli templates` (alias `pnpm manager-cli create --list`)
-- Scaffold without prompts:  
-  `pnpm manager-cli create --variant rrr-server --dir packages/api --name @scope/api --contract @scope/contract --skip-install`
-- Prefer prompts: `pnpm manager-cli create` and follow the menu
-- After scaffolding, open the new package `README.md` for variant-specific scripts and usage
+- Launch interactive manager: `pnpm manager-cli` (package picker → action picker)
+- List templates fast: `pnpm manager-cli templates` (alias `pnpm manager-cli create --list`)
+- Headless scaffold (Codex/CI-ready): `pnpm manager-cli create --variant rrr-server --dir packages/api --name @scope/api --contract @scope/contract --skip-install`
+- Headless publish: `pnpm manager-cli all --non-interactive --bump patch --tag next`
+
+## Running `manager-cli` interactively
+- **Package selection**: scans for every `package.json` (ignores node_modules/dist). Menu entries include each package (color-coded), "All packages", and "Create package". Navigate with ↑/↓/j/k or digits to run instantly.
+- **Action menu** for the selection:
+  - `update dependencies` → runs `pnpm -r update` (or filtered update), stages only dependency files, prompts for a commit message, commits, and pushes.
+  - `test` → `pnpm test` (filtered to the package when possible).
+  - `build` → `pnpm build` (filtered when a single package is selected).
+  - `publish` → ensures the working tree is committed, checks registry auth, prompts a version strategy, commits the bump, tags, publishes with pnpm, and pushes tags.
+  - `full` → update → test → build → publish in order.
+  - `back` → return to package selection. When a single package is chosen, its `package.json` scripts also appear as runnable entries.
+
+## Non-interactive release (Codex/CI)
+- Syntax: `pnpm manager-cli <pkg|all> --non-interactive [publish flags]`
+- Required: the selection (`<pkg>` or `all`) **and** one of `--bump <type>`, `--sync <version>`, or `--noop` (skip version change but still publish/tag).
+- Flags:
+  - `--non-interactive`, `--ci`, `--yes`, `-y` → auto-confirm prompts.
+  - `--bump <patch|minor|major|prepatch|preminor|premajor|prerelease>` → bump versions (pre* keeps/previews prerelease ids).
+  - `--sync <version>` → set all selected packages to an exact version.
+  - `--tag <dist-tag>` → publish with a custom npm dist-tag (default inferred from prerelease suffix).
+  - `--dry-run` → pass through to `pnpm publish --dry-run`.
+  - `--provenance` → enable provenance on publish.
+  - `--noop` → skip version change but still tag/publish current versions.
+- Behavior: commits any existing changes before running (prompting for a message), requires registry auth (`pnpm whoami`), and tags/pushes after publish.
+
+## Scaffolding packages
+- Interactive: `pnpm manager-cli create` → prompts for template, path, package name, contract (for server/client), and client kind (for client/fullstack). Uses arrow keys/digits when the terminal supports raw mode.
+- Headless (Codex/CI) flags:
+  - `--list`, `-l` → show available templates.
+  - `--describe`, `-d <variant>` → print scripts/files/notes for a template.
+  - `--variant`, `-v <id>` → pick a template without a prompt (ids below).
+  - `--dir`, `--path`, `-p <path>` → target directory.
+  - `--name`, `-n <pkg>` → package name (defaults to basename of `--dir`).
+  - `--contract <pkg>` → contract import for server/client templates.
+  - `--client-kind <vite-react|expo-react-native>` → choose client stack (client/fullstack).
+  - `--reset` → delete the target directory before scaffolding.
+  - `--skip-install` / `--skip-build` → skip post-create install/build.
+  - `--help`, `-h` → print help.
+- After effects: ensures the target directory exists (warns if non-empty, or wipes it when `--reset`), writes shared tooling files (tsconfig, workspace helpers), scaffolds the template, runs `pnpm install`, then builds the new package and its workspace deps (fallbacks: full workspace build, then package-only build). Each scaffolded package includes its own README with variant-specific scripts.
 
 ## Templates at a glance
 | id | default dir | summary | key files |
@@ -23,20 +60,19 @@ Dev dependency built for Codex agents: scaffold RRRoutes packages, read the gene
 
 Use `pnpm manager-cli create --describe <variant>` to print the scripts, key files, and notes for any template before scaffolding.
 
-## Create command reference
-- `pnpm manager-cli create --list` — show templates
-- `pnpm manager-cli create --describe rrr-server` — see scripts/files/notes for one template
-- `pnpm manager-cli create --variant rrr-client --dir packages/web-client --name @scope/web-client` — scaffold directly (adds `--contract <id>` for server/client)
-- `--skip-install` / `--skip-build` — bypass post-create steps when you want to install/build later
-
-## Release helper (existing packages)
-- Run from the workspace root; the CLI discovers any workspace packages with a `package.json`.
-- `pnpm manager-cli` launches an interactive menu: pick packages, then run update → test → build → publish (or any single step).
-- Non-interactive publish: `pnpm manager-cli <pkg|all> --non-interactive --bump patch` (see CLI prompts for flags like `--sync` and `--tag`).
+## Agent-ready command crib
+- Scaffold server without prompts:  
+  `pnpm manager-cli create --variant rrr-server --dir packages/api --name @scope/api --contract @scope/contract --skip-install`
+- Scaffold Expo client:  
+  `pnpm manager-cli create --variant rrr-client --dir packages/mobile --name @scope/mobile --contract @scope/contract --client-kind expo-react-native`
+- Publish a single package headlessly:  
+  `pnpm manager-cli @scope/api --non-interactive --bump minor --tag next`
+- Publish everything with a synced version:  
+  `pnpm manager-cli all --non-interactive --sync 1.2.3 --provenance`
 
 ## Notes
-- Each helper script registers the bundled `ts-node/esm` loader with the correct path so the CLI works even when dependencies are hoisted.
-- The create flow runs `pnpm install` and `pnpm run build` when a build script exists; skip with `--skip-install`/`--skip-build` if you want to control timing.
+- Helper scripts register the bundled `ts-node/esm` loader so the CLI works even when dependencies are hoisted.
+- Install/build after scaffolding can be skipped when you need full control (`--skip-install` / `--skip-build`).
 
 ## Tests
 - `pnpm test` verifies the helper CLI loader registration.

package/dist/create-package/index.js

@@ -4,9 +4,10 @@ import path from 'node:path';
 import { stdin as input } from 'node:process';
 import { askLine, promptSingleKey } from '../prompts.js';
 import { colors, logGlobal } from '../utils/log.js';
+import { runHelperCli } from '../helper-cli.js';
 import { loadPackages } from '../packages.js';
 import { SCRIPT_DESCRIPTIONS, workspaceRoot, ensureWorkspaceToolingFiles, } from './shared.js';
-import { clientVariant } from './variants/client.js';
+import { clientVariant, CLIENT_KIND_OPTIONS, DEFAULT_CLIENT_KIND, normalizeClientKind, } from './variants/client.js';
 import { contractVariant } from './variants/contract.js';
 import { dockerVariant } from './variants/docker.js';
 import { emptyVariant } from './variants/empty.js';
@@ -25,6 +26,36 @@ function derivePackageName(targetDir) {
     const base = path.basename(targetDir) || 'rrr-package';
     return base;
 }
+async function promptForContractNameWithHelper(title, options) {
+    let selection;
+    const scripts = options.map((opt) => ({
+        name: opt.label,
+        description: opt.meta ?? '',
+        emoji: '📦',
+        handler: () => {
+            selection = opt.value;
+        },
+    }));
+    scripts.push({
+        name: 'Enter manually',
+        emoji: '⌨️',
+        description: 'Type a contract package name',
+        handler: async () => {
+            const manual = await askLine('Contract package name (e.g. @scope/contract): ');
+            selection = manual.trim() || undefined;
+        },
+    });
+    scripts.push({
+        name: 'Skip (no contract)',
+        emoji: '⏭️',
+        description: 'Continue without a contract dependency',
+        handler: () => {
+            selection = undefined;
+        },
+    });
+    await runHelperCli({ title, scripts, argv: [] });
+    return selection;
+}
 async function promptForContractName() {
     let packages = [];
     try {
@@ -34,39 +65,31 @@ async function promptForContractName() {
         const message = error instanceof Error ? error.message : 'unknown error discovering packages';
         logGlobal(`Could not auto-discover packages (${message}).`, colors.yellow);
     }
-    const candidates = packages
+    const contractOptions = packages
         .filter((pkg) => pkg.relativeDir !== '.')
-        .map((pkg, index) => ({
-        label: `${pkg.name}${pkg.relativeDir ? colors.dim(` (${pkg.relativeDir})`) : ''}`,
+        .map((pkg) => ({
         value: pkg.name,
-        index,
+        label: pkg.name,
+        meta: pkg.relativeDir,
     }));
-    if (candidates.length === 0) {
+    if (contractOptions.length === 0) {
         const manual = await askLine('Contract package name? (Enter to skip, e.g. @scope/contract): ');
         return manual.trim() || undefined;
     }
-    console.log(colors.magenta('Select a contract package (or skip):'));
-    candidates.forEach((opt, idx) => {
-        const prefix = colors.cyan(String(idx + 1).padStart(2, ' '));
-        console.log(`  [${prefix}] ${opt.label}`);
-    });
-    console.log(`  [${colors.cyan('m ')}] Enter manually`);
-    console.log(`  [${colors.cyan('s ')}] Skip (no contract)`);
-    // eslint-disable-next-line no-constant-condition
-    while (true) {
-        const choice = (await askLine('Choice: ')).trim().toLowerCase();
-        if (!choice || choice === 's')
-            return undefined;
-        if (choice === 'm') {
-            const manual = await askLine('Contract package name (e.g. @scope/contract): ');
-            return manual.trim() || undefined;
-        }
-        const idx = Number.parseInt(choice, 10);
-        if (Number.isInteger(idx) && idx >= 1 && idx <= candidates.length) {
-            return candidates[idx - 1].value;
-        }
-        console.log(colors.yellow('Enter a number, "m" to type a name, or "s" to skip.'));
-    }
+    return promptForContractNameWithHelper('Select a contract package (or skip)', contractOptions);
+}
+async function promptForClientKind(existing) {
+    const defaultKind = normalizeClientKind(existing) ?? DEFAULT_CLIENT_KIND;
+    const optionLabels = CLIENT_KIND_OPTIONS.map((opt, idx) => `[${idx + 1}] ${opt.label}`).join(', ');
+    const answer = await askLine(`Client template? ${optionLabels} (${defaultKind}): `);
+    const normalized = normalizeClientKind(answer);
+    if (normalized)
+        return normalized;
+    if (answer === '1')
+        return CLIENT_KIND_OPTIONS[0]?.id ?? defaultKind;
+    if (answer === '2')
+        return CLIENT_KIND_OPTIONS[1]?.id ?? defaultKind;
+    return defaultKind;
 }
 function resolveVariant(key) {
     if (!key)
@@ -141,6 +164,10 @@ function parseCreateCliArgs(argv) {
             options.contractName = argv[++i];
             continue;
         }
+        if (arg === '--client-kind' || arg === '--client') {
+            options.clientKind = argv[++i];
+            continue;
+        }
         if (arg === '--skip-install') {
             options.skipInstall = true;
             continue;
@@ -180,6 +207,7 @@ function printCreateHelp() {
     console.log('  --dir, --path, -p   Target directory (skips path prompt)');
     console.log('  --name, -n          Package name (skips name prompt)');
     console.log('  --contract          Contract import to inject (server/client variants)');
+    console.log('  --client-kind       Client stack (vite-react | expo-react-native)');
     console.log('  --reset             Remove the target directory if it already exists');
     console.log('  --skip-install      Do not run pnpm install after scaffolding');
     console.log('  --skip-build        Skip build after scaffolding');
@@ -421,11 +449,20 @@ async function gatherTarget(initial = {}) {
         contractName === undefined) {
         contractName = await promptForContractName();
     }
+    let clientKind = initial.clientKind;
+    if (variant.id === 'rrr-client' || variant.id === 'rrr-fullstack') {
+        const normalizedKind = normalizeClientKind(clientKind);
+        clientKind = normalizedKind ?? clientKind;
+        if (!clientKind) {
+            clientKind = await promptForClientKind();
+        }
+    }
     return {
         variant,
         targetDir,
         pkgName,
         contractName,
+        clientKind,
         reset: initial.reset,
     };
 }
@@ -438,6 +475,7 @@ export async function createRrrPackage(options = {}) {
         targetDir: target.targetDir,
         pkgName: target.pkgName,
         contractName: target.contractName ?? options.contractName,
+        clientKind: target.clientKind ?? options.clientKind,
     });
     await postCreateTasks(target.targetDir, {
         skipInstall: options.skipInstall,
@@ -476,6 +514,7 @@ export async function runCreatePackageCli(argv) {
         targetDir,
         pkgName: parsed.pkgName,
         contractName: parsed.contractName,
+        clientKind: normalizeClientKind(parsed.clientKind),
         reset: parsed.reset,
         skipInstall: parsed.skipInstall,
         skipBuild: parsed.skipBuild ?? parsed.skipInstall,