@emeryld/manager 0.5.1 → 0.6.1

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

@@ -7,7 +7,7 @@ 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';
@@ -78,6 +78,32 @@ async function promptForContractName() {
     }
     return promptForContractNameWithHelper('Select a contract package (or skip)', contractOptions);
 }
+async function promptForClientKind(existing) {
+    const defaultKind = normalizeClientKind(existing) ?? DEFAULT_CLIENT_KIND;
+    let selection;
+    const scripts = CLIENT_KIND_OPTIONS.map((opt) => ({
+        name: opt.label,
+        emoji: '💻',
+        description: opt.summary,
+        handler: () => {
+            selection = opt.id;
+        },
+    }));
+    scripts.push({
+        name: `Use default (${defaultKind})`,
+        emoji: '✅',
+        description: 'Keep the prior/default choice',
+        handler: () => {
+            selection = defaultKind;
+        },
+    });
+    await runHelperCli({
+        title: 'Select a client template',
+        scripts,
+        argv: [],
+    });
+    return selection ?? defaultKind;
+}
 function resolveVariant(key) {
     if (!key)
         return undefined;
@@ -151,6 +177,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;
@@ -190,6 +220,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');
@@ -431,11 +462,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,
     };
 }
@@ -448,6 +488,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,
@@ -486,6 +527,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,