@mono-labs/cli 0.0.203 → 0.0.205

package/README.md

@@ -1,247 +1,123 @@
-<div align="center">
+# mono-labs
 
-# mono-labs CLI
-
-Declarative, token-aware task runner for JavaScript/TypeScript monorepos.
-Configure commands with simple JSON – no custom scripting required.
-
-</div>
-
-## Why This Exists
-
-You often need a repeatable set of steps to bootstrap or run your full stack
-(web, mobile, backend, infra). Traditional npm scripts become tangled. This CLI
-lets you:
-
-- Describe commands in `.mono/*.json` files
-- Emit dynamic values from scripts (`{out:token value}`)
-- Inject those values into later commands & environment variables
-- Run multiple background services + one attached foreground process
-
-No publishing needed: you can link and iterate locally.
+Declarative monorepo orchestration, project tooling, and infrastructure
+integration — built to scale real systems, not just scripts.
 
 ---
 
-## Quick Start (Beginner Friendly)
+## What This Is
 
-1. Install dependencies:
+mono-labs is a monorepo control plane.
 
-```bash
-yarn install
-```
+It combines:
 
-2. Create a `.mono` directory in your project root.
-3. Add a file `.mono/hello.json`:
-
-```json
-{ "actions": ["echo Hello World"] }
-```
+- a declarative, token-aware CLI runtime
+- project-level orchestration utilities
+- infrastructure and CI integration primitives
 
-4. Run the command:
+The goal is to make a monorepo behave like a single, coordinated system across:
 
-```bash
-yarn mono hello
-```
-
-You should see `Hello World`.
-
-### Adding a Command with an Argument
-
-```json
-// .mono/greet.json
-{
-	"actions": ["echo Hi ${arg}"],
-	"argument": { "description": "Name to greet", "default": "friend" }
-}
-```
-
-```bash
-yarn mono greet        # Hi friend
-yarn mono greet Alice  # Hi Alice
-```
-
-### Adding an Option
-
-```json
-// .mono/build.json
-{
-	"actions": ["echo Building for ${platform} debug=${debug}"],
-	"options": {
-		"platform": { "type": "string", "default": "ios" },
-		"debug": { "description": "Enable debug mode" }
-	}
-}
-```
-
-```bash
-yarn mono build --platform android --debug
-```
+- local development
+- CI pipelines
+- deployments
+- infrastructure management
 
 ---
 
-## Core Concepts
-
-| Concept        | Summary                                                                                       |
-| -------------- | --------------------------------------------------------------------------------------------- |
-| `.mono/*.json` | Each file (except `config.json`) becomes a command. `dev.json` -> `yarn mono dev`.            |
-| `preactions`   | Sequential setup commands whose output can define tokens.                                     |
-| `actions`      | Main workload commands. All but last run detached; last is attached (interactive).            |
-| Tokens         | Printed from preactions as `{out:key value}` and later substituted as `${key}`.               |
-| Environments   | `environments.dev` / `environments.stage` provide token-aware env vars. Use `--stage` switch. |
-| Data Layer     | Merges defaults, user flags, argument, and emitted tokens.                                    |
+## What Problems It Solves
 
-Full schemas & rules: see `docs/configuration.md`.
+Most monorepos suffer from:
 
----
+- duplicated scripts across packages
+- environment drift between dev and CI
+- infrastructure logic isolated in pipelines
+- brittle bash scripts
+- slow onboarding
 
-## Documentation Index
+mono-labs solves this by providing:
 
-| Topic                    | File                      |
-| ------------------------ | ------------------------- |
-| Architecture / internals | `docs/architecture.md`    |
-| Configuration schema     | `docs/configuration.md`   |
-| Practical examples       | `docs/examples.md`        |
-| Troubleshooting          | `docs/troubleshooting.md` |
+- declarative command definitions
+- shared runtime state via tokens
+- reusable project utilities
+- programmatic CDK helpers
+- one mental model for dev, CI, and deploy
 
 ---
 
-## How It Works (Short Version)
+## High-Level Architecture
 
-1. CLI scans `.mono/` at startup.
-2. Builds Commander commands for each JSON file.
-3. When invoked: merges defaults + flags + argument into data layer.
-4. Runs `preactions` (foreground) capturing `{out:key value}` tokens.
-5. Spawns each action (background except last). Performs `${token}`
-   substitution.
-6. Cleans background processes on exit or Ctrl+C.
+mono-labs is intentionally layered:
 
-Details: `docs/architecture.md`.
+1. `.mono/` Declarative command definitions (JSON).
 
----
-
-## Local Development / Linking
+2. CLI Runtime (`bin` + `lib`) Loads `.mono`, builds commands, executes
+   workflows, manages processes.
 
-From this repo root:
+3. Project Orchestration (`src/project`) Environment merging, configuration
+   management, monorepo utilities.
 
-```bash
-yarn link
-```
+4. Infrastructure Integration (`src/cdk`) CDK helpers, stack orchestration,
+   CI-friendly deployment primitives.
 
-In a target project:
+Each layer can be used independently, but they are designed to work together.
 
-```bash
-yarn link "@mono-labs/cli"
-```
+---
 
-Then use:
+## Quick Start
 
-```bash
-yarn mono <command>
-```
+Create a `.mono` directory and add:
 
-To unlink later:
+.mono/hello.json
 
-```bash
-yarn unlink "@mono-labs/cli"
-```
+{ "actions": ["echo Hello World"] }
 
-Alternative (direct file install):
+Run:
 
-```bash
-yarn add file:/absolute/path/to/mono-labs-cli
-```
+yarn mono hello
 
 ---
 
-## Emitting Dynamic Values
+## Typical Developer Workflow
 
-Inside a `preactions` script output lines like:
+yarn mono dev yarn mono serve yarn mono mobile
 
-```
-{out:ngrok_api https://1234.ngrok.dev}
-{out:region us-east-1}
-```
+If unsure:
 
-Then reference in actions or environments as `${ngrok_api}` or `${region}`.
+yarn mono help
 
 ---
 
-## Example Advanced Command
-
-```json
-// .mono/dev.json
-{
-	"preactions": ["docker compose up -d", "node scripts/ngrok_setup"],
-	"actions": [
-		"yarn backend dynamodb-admin -p 8082 --dynamo-endpoint=http://localhost:8000",
-		"yarn mono backend server"
-	],
-	"argument": { "type": "string", "default": "dev" },
-	"options": {
-		"stage": { "description": "Use stage env" },
-		"profile": { "type": "string", "description": "Profile name" }
-	},
-	"environments": {
-		"dev": { "API_URL": "${ngrok_api}", "MODE": "dev" },
-		"stage": { "API_URL": "${ngrok_api}", "MODE": "stage" }
-	}
-}
-```
-
-Run:
-
-```bash
-yarn mono dev --profile alpha
-```
+## Documentation Index
 
----
+Start here:
 
-## Design Decisions
+- docs/README.txt
 
-- JSON over JS: simpler, toolable, safer for newcomers.
-- Single positional argument: keeps mental model small.
-- Token system: decouples script output from later steps.
-- Background/foreground split: stable dev server orchestration.
+Key docs:
 
----
+- docs/architecture.md
+- docs/configuration.md
+- docs/examples.md
+- docs/troubleshooting.md
 
-## Extending
+Advanced:
 
-| Need                   | Approach                                      |
-| ---------------------- | --------------------------------------------- |
-| Multiple arguments     | Extend `cliFactory.js` to parse more.         |
-| JSON schema validation | Add Ajv in `boot()` loader.                   |
-| Parallel preactions    | Modify `runHasteCommand.js` to `Promise.all`. |
-| Different token syntax | Adjust regex in `runForeground.js`.           |
+- docs/project-orchestration.md
+- docs/infrastructure-integration.md
 
 ---
 
-## Contributing
+## Who This Is For
 
-1. Fork & clone
-2. Create a feature branch
-3. Add/adjust tests (future roadmap)
-4. Submit PR with clear description
+mono-labs is designed for teams that:
 
----
-
-## FAQ (Fast Answers)
-
-| Question                         | Answer                                                                                                                    |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| How do I list commands?          | Look at filenames in `.mono/` or run `yarn mono --help`.                                                                  |
-| How do I pass env vars manually? | `MY_VAR=1 yarn mono dev` (POSIX) or `set MY_VAR=1 && yarn mono dev` (CMD) or `$env:MY_VAR=1; yarn mono dev` (PowerShell). |
-| Does it support Windows?         | Yes; process cleanup uses `taskkill`.                                                                                     |
-| What if a token is missing?      | It stays literal (`${token}`); no crash.                                                                                  |
+- run full-stack systems
+- manage real infrastructure
+- care about reproducibility
+- want dev and CI to behave the same
 
 ---
 
 ## License
 
 MIT © Contributors
-
----
-
-## Next Steps
-
-Jump to: `docs/examples.md` for hands-on learning.

package/dist/project/build-mono-readme.js

@@ -0,0 +1,272 @@
+// scripts/generate-readme.ts
+// Node >= 18 recommended
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { generateDocsIndex } from './generate-docs.js';
+/* -------------------------------------------------------------------------- */
+/*                               Path helpers                                 */
+/* -------------------------------------------------------------------------- */
+// Always use the working directory as the root for all file actions
+const REPO_ROOT = path.resolve(process.cwd());
+const MONO_DIR = path.join(REPO_ROOT, '.mono');
+const ROOT_PKG_JSON = path.join(REPO_ROOT, 'package.json');
+const OUTPUT_PATH = path.join(REPO_ROOT, 'docs');
+const OUTPUT_README = path.join(OUTPUT_PATH, 'command-line.md');
+/* -------------------------------------------------------------------------- */
+/*                                   Utils                                    */
+/* -------------------------------------------------------------------------- */
+async function ensureParentDir(filePath) {
+    // Always resolve parent dir relative to working directory
+    const dir = path.resolve(process.cwd(), path.dirname(filePath));
+    await fs.mkdir(dir, { recursive: true });
+}
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
+async function readJson(filePath) {
+    // Always resolve filePath relative to working directory
+    const absPath = path.resolve(process.cwd(), filePath);
+    const raw = await fs.readFile(absPath, 'utf8');
+    return JSON.parse(raw);
+}
+async function listDir(dir) {
+    // Always resolve dir relative to working directory
+    const absDir = path.resolve(process.cwd(), dir);
+    return fs.readdir(absDir, { withFileTypes: true });
+}
+function normalizeWorkspacePatterns(workspacesField) {
+    if (Array.isArray(workspacesField))
+        return workspacesField;
+    if (isObject(workspacesField) &&
+        Array.isArray(workspacesField.packages)) {
+        return workspacesField.packages;
+    }
+    return [];
+}
+function mdEscapeInline(value) {
+    return String(value ?? '').replaceAll('`', '\\`');
+}
+function indentLines(s, spaces = 2) {
+    const pad = ' '.repeat(spaces);
+    return s
+        .split('\n')
+        .map((line) => pad + line)
+        .join('\n');
+}
+/* -------------------------------------------------------------------------- */
+/*                      Workspace glob pattern expansion                       */
+/* -------------------------------------------------------------------------- */
+function matchSegment(patternSeg, name) {
+    if (patternSeg === '*')
+        return true;
+    if (!patternSeg.includes('*'))
+        return patternSeg === name;
+    const escaped = patternSeg.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(`^${escaped.replaceAll('*', '.*')}$`);
+    return regex.test(name);
+}
+async function expandWorkspacePattern(root, pattern) {
+    const segments = toPosix(pattern).split('/').filter(Boolean);
+    async function expandFrom(dir, index) {
+        // Always resolve dir relative to working directory
+        const absDir = path.resolve(process.cwd(), dir);
+        if (index >= segments.length)
+            return [absDir];
+        const seg = segments[index];
+        if (seg === '**') {
+            const results = [];
+            results.push(...(await expandFrom(absDir, index + 1)));
+            const entries = await fs
+                .readdir(absDir, { withFileTypes: true })
+                .catch(() => []);
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                results.push(...(await expandFrom(path.join(absDir, entry.name), index)));
+            }
+            return results;
+        }
+        const entries = await fs
+            .readdir(absDir, { withFileTypes: true })
+            .catch(() => []);
+        const results = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (!matchSegment(seg, entry.name))
+                continue;
+            results.push(...(await expandFrom(path.join(absDir, entry.name), index + 1)));
+        }
+        return results;
+    }
+    const dirs = await expandFrom(root, 0);
+    const pkgDirs = [];
+    for (const d of dirs) {
+        if (await exists(path.join(d, 'package.json'))) {
+            pkgDirs.push(d);
+        }
+    }
+    return Array.from(new Set(pkgDirs));
+}
+async function findWorkspacePackageDirs(repoRoot, patterns) {
+    const dirs = [];
+    for (const pat of patterns) {
+        dirs.push(...(await expandWorkspacePattern(repoRoot, pat)));
+    }
+    return Array.from(new Set(dirs));
+}
+/* -------------------------------------------------------------------------- */
+/*                             .mono configuration                             */
+/* -------------------------------------------------------------------------- */
+async function readMonoConfig() {
+    // Always resolve configPath relative to working directory
+    const configPath = path.resolve(process.cwd(), path.join(MONO_DIR, 'config.json'));
+    if (!(await exists(configPath)))
+        return null;
+    try {
+        const config = await readJson(configPath);
+        return { path: configPath, config };
+    }
+    catch {
+        return null;
+    }
+}
+function commandNameFromFile(filePath) {
+    return path.basename(filePath).replace(/\.json$/i, '');
+}
+async function readMonoCommands() {
+    // Always resolve MONO_DIR relative to working directory
+    const monoDirAbs = path.resolve(process.cwd(), MONO_DIR);
+    if (!(await exists(monoDirAbs)))
+        return [];
+    const entries = await listDir(monoDirAbs);
+    const jsonFiles = entries
+        .filter((e) => e.isFile() && e.name.endsWith('.json'))
+        .map((e) => path.join(monoDirAbs, e.name))
+        .filter((p) => path.basename(p) !== 'config.json');
+    const commands = [];
+    for (const file of jsonFiles) {
+        try {
+            const json = await readJson(file);
+            commands.push({
+                name: commandNameFromFile(file),
+                file,
+                json,
+            });
+        }
+        catch {
+            /* ignore invalid JSON */
+        }
+    }
+    return commands.sort((a, b) => a.name.localeCompare(b.name));
+}
+/* -------------------------------------------------------------------------- */
+/*                          Options schema parsing                             */
+/* -------------------------------------------------------------------------- */
+function parseOptionsSchema(optionsObj) {
+    if (!isObject(optionsObj))
+        return [];
+    const entries = Object.entries(optionsObj).map(([key, raw]) => {
+        const o = isObject(raw) ? raw : {};
+        const hasType = typeof o.type === 'string' && o.type.length > 0;
+        return {
+            key,
+            kind: hasType ? 'value' : 'boolean',
+            type: hasType ? o.type : 'boolean',
+            description: typeof o.description === 'string' ? o.description : '',
+            shortcut: typeof o.shortcut === 'string' ? o.shortcut : '',
+            default: o.default,
+            allowed: Array.isArray(o.options) ? o.options : null,
+            allowAll: o.allowAll === true,
+        };
+    });
+    return entries.sort((a, b) => a.key.localeCompare(b.key));
+}
+/* -------------------------------------------------------------------------- */
+/*                                 Formatting                                 */
+/* -------------------------------------------------------------------------- */
+function buildUsageExample(commandName, cmdJson, options) {
+    const arg = cmdJson.argument;
+    const hasArg = isObject(arg);
+    const parts = [`yarn mono ${commandName}`];
+    if (hasArg)
+        parts.push(`<${commandName}-arg>`);
+    const valueOpts = options.filter((o) => o.kind === 'value');
+    const boolOpts = options.filter((o) => o.kind === 'boolean');
+    for (const o of valueOpts.slice(0, 2)) {
+        const value = o.default !== undefined ?
+            String(o.default)
+            : (o.allowed?.[0] ?? '<value>');
+        parts.push(`--${o.key} ${value}`);
+    }
+    if (boolOpts[0]) {
+        parts.push(`--${boolOpts[0].key}`);
+    }
+    return parts.join(' ');
+}
+/* -------------------------------------------------------------------------- */
+/*                                    Main                                    */
+/* -------------------------------------------------------------------------- */
+async function main() {
+    // Always resolve all paths relative to working directory
+    if (!(await exists(ROOT_PKG_JSON))) {
+        throw new Error(`Missing ${ROOT_PKG_JSON}`);
+    }
+    await ensureParentDir(OUTPUT_PATH);
+    const rootPkg = await readJson(ROOT_PKG_JSON);
+    const workspacePatterns = normalizeWorkspacePatterns(rootPkg.workspaces);
+    const monoConfig = await readMonoConfig();
+    const monoCommands = await readMonoCommands();
+    const pkgDirs = await findWorkspacePackageDirs(REPO_ROOT, workspacePatterns);
+    const packages = [];
+    for (const dir of pkgDirs) {
+        try {
+            const pkg = await readJson(path.join(dir, 'package.json'));
+            packages.push({
+                name: pkg.name ??
+                    toPosix(path.relative(REPO_ROOT, dir)) ??
+                    path.basename(dir),
+                dir,
+                scripts: pkg.scripts ?? {},
+            });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const parts = [];
+    parts.push(`# Mono Command-Line Reference
+
+> Generated by \`scripts/generate-readme.ts\`.
+
+`);
+    // Reuse your existing formatters here
+    // (unchanged logic, now fully typed)
+    const docsIndex = await generateDocsIndex({
+        docsDir: path.join(REPO_ROOT, 'docs'),
+        excludeFile: 'command-line.md',
+    });
+    parts.push(docsIndex);
+    await ensureParentDir(OUTPUT_README);
+    await fs.writeFile(OUTPUT_README, parts.join('\n'), 'utf8');
+    console.log(`Generated: ${OUTPUT_README}`);
+    console.log(`- mono config: ${monoConfig ? 'yes' : 'no'}`);
+    console.log(`- mono commands: ${monoCommands.length}`);
+    console.log(`- workspace packages: ${packages.length}`);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.stack : err);
+    process.exit(1);
+});

package/dist/project/build-readme.js

@@ -0,0 +1,2 @@
+import './build-mono-readme';
+import './generate-readme';

package/dist/project/generate-docs.js

@@ -0,0 +1,53 @@
+// scripts/generate-repo-help.mjs
+// Generates a developer-friendly workspace command reference.
+//
+// Output: docs/workspaces.md
+//
+// Run (from repo root):
+//   node ./scripts/generate-repo-help.mjs
+//
+// Philosophy:
+// - Optimize for onboarding and day-to-day use
+// - Keep raw yarn workspace commands for reference
+// - Emphasize `yarn mono` as the primary interface
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/**
+ * Generate a docs index from markdown files.
+ *
+ * @param options - Options for docs index generation
+ * @returns Markdown-formatted index
+ */
+export async function generateDocsIndex({ docsDir, excludeFile, }) {
+    // Always resolve docsDir relative to the working directory
+    const dirPath = path.resolve(process.cwd(), docsDir);
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const links = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.md'))
+            continue;
+        // Always ignore docs/readme.md (case-insensitive)
+        if (entry.name.toLowerCase() === 'readme.md')
+            continue;
+        // Optionally ignore a caller-specified file
+        if (excludeFile && entry.name === excludeFile)
+            continue;
+        const filePath = path.join(dirPath, entry.name);
+        const contents = await fs.readFile(filePath, 'utf8');
+        // Find first markdown H1
+        const match = contents.match(/^#\s+(.+)$/m);
+        if (!match)
+            continue;
+        const title = match[1].trim();
+        const relativeLink = `./${entry.name}`;
+        links.push(`[${title}](${relativeLink})`);
+    }
+    // Sort alphabetically by title for stability
+    links.sort((a, b) => a.localeCompare(b));
+    // Append Back to Readme (hardcoded)
+    links.push('');
+    links.push('[Back to Readme](../README.md)');
+    return links.join('\n');
+}