@chris-lally/cli 0.1.0-alpha.1 → 0.1.0-alpha.6

package/README.md

@@ -1,6 +1,8 @@
 # @chris-lally/cli
 
-CLI for the `@chris-lally/*` ecosystem.
+CLI for `@chris-lally/cli`.
+
+> This README is auto-generated by `lally update readme --target cli`.
 
 ## Install
 
@@ -14,16 +16,184 @@ or run with `pnpm dlx`:
 pnpm dlx @chris-lally/cli@alpha --help
 ```
 
-## Commands
+### `lally --help`
+
+```text
+lally
+
+Usage:
+  lally <command> [options]
+
+Commands:
+  init      Initialize app config/presets
+  add       Add scaffolds (fumadocs, db)
+  check     Validate project setup (read-only)
+  clean     Clean template leftovers (safe dry-run default)
+  update    Run maintenance/update utilities
+  release   Publish @chris-lally packages
+
+Command usage:
+  lally init [fumadocs/base-path] [--app <path>]
+  lally add <namespace/item> [--app <path>]
+  lally check fumadocs [--app <path>] [--strict-layout] [--json]
+  lally clean fumadocs [--app <path>] [--keep <glob>] [--apply] [--delete]
+  lally update subtree --script <script-name> [--dir <path>] [--json]
+  lally update layout --preset notebook-topnav [--app <path>]
+  lally update readme --target <name> [--check]
+  lally release <target> --tag <tag> [--dry-run] [--json]
+
+Examples:
+  lally init fumadocs/base-path --app apps/web
+  lally add fumadocs/sidebar-history
+  lally add fumadocs/section --name handbook --app apps/web
+  lally check fumadocs --app apps/web
+  lally check fumadocs --app apps/web --strict-layout
+  lally clean fumadocs --app apps/web
+  lally clean fumadocs --app apps/web --apply
+  lally add db/local-postgres --app apps/web
+  lally update subtree --script sync-push.sh
+  lally update subtree --target statements --action push
+  lally update layout --preset notebook-topnav --app apps/web
+  lally update readme --target cli
+  lally release fumadocs --tag alpha --dry-run
+
+Notes:
+  - Use --app when running from monorepo root.
+  - `clean` is dry-run by default; add --apply to execute.
+  - For detailed help: lally <command> --help
+```
+
+### `lally init --help`
+
+```text
+Usage:
+  lally init [preset] [--app <path>]
+
+Presets:
+  fumadocs/base-path   Initialize content root + Next basePath from lally.config.json
+
+Deprecated aliases:
+  fumadocs/dashboard   Alias for fumadocs/base-path
+
+Examples:
+  lally init --app apps/web
+  lally init fumadocs/base-path --app apps/web
+
+Notes:
+  - If run from monorepo root, pass --app.
+  - Uses lally.config.json fumadocs.basePath/contentRoot defaults.
+```
+
+### `lally add --help`
+
+```text
+Usage:
+  lally add <namespace/item> [--app <path>]
+
+Supported items:
+  fumadocs/section         Add a root section under content/<contentRoot>
+  fumadocs/page-shell      Add a notebook page shell component
+  fumadocs/sidebar-history Add global sidebar history banner wiring
+  db/local-postgres        Add local DB create/migrate/reset scripts
+  db/master-migration      Add db/migrations/tables.sql scaffold
+  db/seed-script           Add local seed script + package scripts
+
+Examples:
+  lally add fumadocs/section --name handbook --app apps/web
+  lally add fumadocs/page-shell --app apps/web
+  lally add db/local-postgres --app apps/web
+
+Notes:
+  - If run from monorepo root, pass --app.
+  - Uses lally.config.json fumadocs.basePath/contentRoot when available.
+```
 
-- `lally init`
-- `lally add <namespace/item>`
-- `lally release <target> --tag <tag> [--dry-run] [--json]`
+### `lally check --help`
 
-Example:
+```text
+Usage:
+  lally check fumadocs [--app <path>] [--strict-layout] [--json]
 
-- `lally add fumadocs/sidebar-history`
-- `lally release fumadocs --tag alpha --dry-run`
+Checks:
+  - required .gitignore entries
+  - required app files (next.config, source.config, src/lib/source)
+  - optional strict layout preset wiring (with --strict-layout)
+
+Examples:
+  lally check fumadocs --app apps/web
+  lally check fumadocs --app apps/web --strict-layout
+  lally check fumadocs --app apps/web --json
+```
+
+### `lally clean --help`
+
+```text
+Usage:
+  lally clean fumadocs [--app <path>] [--keep <glob>] [--archive-dir <path>] [--apply] [--delete] [--json]
+
+Safety defaults:
+  - dry-run by default (no file changes)
+  - use --apply to execute
+  - apply mode archives files by default
+  - use --delete to permanently remove instead of archive
+
+Examples:
+  lally clean fumadocs --app apps/web
+  lally clean fumadocs --app apps/web --keep 'content/docs/custom/**'
+  lally clean fumadocs --app apps/web --apply
+  lally clean fumadocs --app apps/web --apply --archive-dir .lally-clean-backup/manual-1
+  lally clean fumadocs --app apps/web --apply --delete
+```
+
+### `lally update --help`
+
+```text
+Usage:
+  lally update subtree --script <script-name> [--dir <path>] [--json]
+  lally update subtree --target <name> --action <push|pull> [--dir <path>] [--json]
+  lally update layout --preset notebook-topnav [--app <path>]
+  lally update readme [--target <name>] [--check] [--print]
+
+Notes:
+  - subtree uses update.subtree config in lally.config.json
+  - project.subtree is still supported as a fallback
+  - readme uses readme.targets config in lally.config.json
+  - readme auto-discovers top-level commands from <bin> --help
+
+Examples:
+  lally update subtree --script sync-push.sh
+  lally update subtree --target statements --action push
+  lally update layout --preset notebook-topnav --app apps/web
+  lally update readme --target cli
+  lally update readme --target cli --check
+```
+
+### `lally release --help`
+
+```text
+Usage:
+  lally release <target> --tag <tag> [--dry-run] [--json]
+
+Targets:
+  fumadocs   Publish @chris-lally/fumadocs
+  cli        Publish @chris-lally/cli
+
+Examples:
+  lally release fumadocs --tag alpha --dry-run
+  lally release fumadocs --tag alpha --json
+
+Notes:
+  - For target=cli, README is regenerated automatically before build.
+
+Auth resolution (first match wins):
+  1) NPM_CONFIG_USERCONFIG env var (explicit path)
+  2) generated temp npmrc from NPM_TOKEN (auto)
+  3) <repo>/.npmrc.publish
+  4) <repo>/.npmrc
+  5) default npm user config (e.g. ~/.npmrc from npm login)
+
+NPM_TOKEN can be provided via shell env or repo .env.
+```
 
 ## License
 

package/dist/bin/lally.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=lally.d.ts.map

package/dist/commands/add/db.d.ts

@@ -0,0 +1,3 @@
+export declare function addDbLocalPostgres(appRoot: string): Promise<void>;
+export declare function addDbMasterMigration(appRoot: string): Promise<void>;
+export declare function addDbSeedScript(appRoot: string): Promise<void>;

package/dist/commands/add/db.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addDbLocalPostgres = addDbLocalPostgres;
+exports.addDbMasterMigration = addDbMasterMigration;
+exports.addDbSeedScript = addDbSeedScript;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const shared_1 = require("./shared");
+async function addDbLocalPostgres(appRoot) {
+    const createScriptPath = (0, node_path_1.resolve)(appRoot, "db/scripts/create-local-db.sh");
+    const createScript = `#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "\${DATABASE_URL:-}" ]; then
+  echo "Missing DATABASE_URL"
+  exit 1
+fi
+
+if ! command -v psql >/dev/null 2>&1; then
+  echo "psql is required"
+  exit 1
+fi
+
+DB_NAME=$(echo "$DATABASE_URL" | sed -E 's#^.*/([^/?]+).*$#\\1#')
+if [ -z "$DB_NAME" ]; then
+  echo "Could not parse database name from DATABASE_URL"
+  exit 1
+fi
+
+if psql "$DATABASE_URL" -c "select 1" >/dev/null 2>&1; then
+  echo "Database already exists and is reachable: $DB_NAME"
+  exit 0
+fi
+
+BASE_URL=$(echo "$DATABASE_URL" | sed -E 's#/(.+)$##')
+psql "$BASE_URL/postgres" -c "CREATE DATABASE \"$DB_NAME\";" || true
+
+echo "Ensured database exists: $DB_NAME"
+`;
+    const scriptResult = await (0, shared_1.ensureFile)(createScriptPath, createScript);
+    if (scriptResult === "created") {
+        await (0, promises_1.writeFile)(createScriptPath, createScript, { mode: 0o755 });
+    }
+    const packageJsonPath = (0, node_path_1.resolve)(appRoot, "package.json");
+    const packageJson = await (0, shared_1.loadJson)(packageJsonPath);
+    if (packageJson) {
+        const scripts = packageJson.scripts ?? {};
+        scripts["db:create:local"] = scripts["db:create:local"] ?? "dotenv -e .env -- bash ./db/scripts/create-local-db.sh";
+        scripts["db:migrate:local"] =
+            scripts["db:migrate:local"] ??
+                "dotenv -e .env -- sh -c 'psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f db/migrations/tables.sql'";
+        scripts["db:reset:local"] =
+            scripts["db:reset:local"] ??
+                "dotenv -e .env -- sh -c 'psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -c \"DROP SCHEMA public CASCADE; CREATE SCHEMA public;\"' && pnpm run db:migrate:local";
+        scripts["db:setup:local"] = scripts["db:setup:local"] ?? "pnpm run db:create:local && pnpm run db:migrate:local";
+        packageJson.scripts = scripts;
+        const devDependencies = packageJson.devDependencies ?? {};
+        if (!devDependencies["dotenv-cli"])
+            devDependencies["dotenv-cli"] = "^11.0.0";
+        packageJson.devDependencies = devDependencies;
+        await (0, shared_1.ensureJsonFile)(packageJsonPath, packageJson);
+        console.log("Updated package.json DB scripts (local postgres)");
+    }
+}
+async function addDbMasterMigration(appRoot) {
+    const tablesPath = (0, node_path_1.resolve)(appRoot, "db/migrations/tables.sql");
+    const content = `-- ============================================================================
+-- MASTER TABLE MIGRATION
+-- Update this file in place as schema evolves; rely on git history for changes.
+-- ============================================================================
+
+set search_path to public;
+create extension if not exists pgcrypto;
+
+-- Add your tables below.
+`;
+    const result = await (0, shared_1.ensureFile)(tablesPath, content);
+    console.log(result === "created" ? `Created ${tablesPath}` : `Skipped ${tablesPath} (already exists)`);
+}
+async function addDbSeedScript(appRoot) {
+    const seedPath = (0, node_path_1.resolve)(appRoot, "db/scripts/seed-local.sh");
+    const seed = `#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "\${DATABASE_URL:-}" ]; then
+  echo "Missing DATABASE_URL"
+  exit 1
+fi
+
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 <<'SQL'
+set search_path to public;
+
+-- Add seed rows here. Keep idempotent where possible.
+SQL
+
+echo "Seed complete"
+`;
+    const result = await (0, shared_1.ensureFile)(seedPath, seed);
+    if (result === "created") {
+        await (0, promises_1.writeFile)(seedPath, seed, { mode: 0o755 });
+    }
+    const packageJsonPath = (0, node_path_1.resolve)(appRoot, "package.json");
+    const packageJson = await (0, shared_1.loadJson)(packageJsonPath);
+    if (packageJson) {
+        const scripts = packageJson.scripts ?? {};
+        scripts["db:seed:local"] = scripts["db:seed:local"] ?? "dotenv -e .env -- bash ./db/scripts/seed-local.sh";
+        scripts["db:setup-and-seed:local"] =
+            scripts["db:setup-and-seed:local"] ?? "pnpm run db:setup:local && pnpm run db:seed:local";
+        packageJson.scripts = scripts;
+        const devDependencies = packageJson.devDependencies ?? {};
+        if (!devDependencies["dotenv-cli"])
+            devDependencies["dotenv-cli"] = "^11.0.0";
+        packageJson.devDependencies = devDependencies;
+        await (0, shared_1.ensureJsonFile)(packageJsonPath, packageJson);
+        console.log("Updated package.json seed scripts");
+    }
+}
+//# sourceMappingURL=db.js.map

package/dist/commands/add/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../../src/commands/add/db.ts"],"names":[],"mappings":"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"}

package/dist/commands/add/fumadocs.d.ts

@@ -0,0 +1,3 @@
+export declare function addFumadocsSection(appRoot: string, sectionName: string): Promise<void>;
+export declare function addPageShell(appRoot: string): Promise<void>;
+export declare function addSidebarHistory(appRoot: string): Promise<void>;

package/dist/commands/add/fumadocs.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addFumadocsSection = addFumadocsSection;
+exports.addPageShell = addPageShell;
+exports.addSidebarHistory = addSidebarHistory;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const shared_1 = require("./shared");
+async function addFumadocsSection(appRoot, sectionName) {
+    const sectionSlug = sectionName.trim().toLowerCase().replace(/\s+/g, "-");
+    const sectionTitle = (0, shared_1.toTitleCase)(sectionSlug);
+    const { contentRoot } = await (0, shared_1.getFumadocsSettings)(appRoot);
+    const rootMetaPath = (0, node_path_1.resolve)(appRoot, `content/${contentRoot}/meta.json`);
+    const currentMeta = (await (0, shared_1.loadJson)(rootMetaPath)) ?? {
+        title: (0, shared_1.toTitleCase)(contentRoot),
+        root: true,
+        pages: [],
+    };
+    const pages = new Set(currentMeta.pages ?? []);
+    pages.add(sectionSlug);
+    await (0, shared_1.ensureJsonFile)(rootMetaPath, {
+        title: currentMeta.title ?? (0, shared_1.toTitleCase)(contentRoot),
+        root: true,
+        pages: Array.from(pages),
+    });
+    const sectionMetaPath = (0, node_path_1.resolve)(appRoot, `content/${contentRoot}/${sectionSlug}/meta.json`);
+    const sectionIndexPath = (0, node_path_1.resolve)(appRoot, `content/${contentRoot}/${sectionSlug}/index.mdx`);
+    await (0, shared_1.ensureJsonFile)(sectionMetaPath, {
+        title: sectionTitle,
+        root: true,
+        pages: ["index"],
+    });
+    await (0, shared_1.ensureFile)(sectionIndexPath, `---\ntitle: ${sectionTitle}\ndescription: ${sectionTitle} section\n---\n\nWelcome to ${sectionTitle}.\n`);
+    console.log(`Added section content: content/${contentRoot}/${sectionSlug}`);
+    console.log("Next: wire this section into source.config.ts and src/lib/source.ts if needed.");
+}
+async function addPageShell(appRoot) {
+    const target = (0, node_path_1.resolve)(appRoot, "src/components/notebook/custom-page-shell.tsx");
+    const content = `import type { ReactNode } from 'react';
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/notebook/page';
+import { LLMCopyButton, ViewOptions } from '@/components/ai/page-actions';
+import { gitConfig } from '@/lib/layout.shared';
+
+type CustomPageShellProps = {
+  title: string;
+  description: string;
+  markdownUrl: string;
+  githubContentPath: string;
+  children: ReactNode;
+};
+
+export function CustomPageShell({
+  title,
+  description,
+  markdownUrl,
+  githubContentPath,
+  children,
+}: CustomPageShellProps) {
+  const githubUrl = \`https://github.com/\${gitConfig.user}/\${gitConfig.repo}/blob/\${gitConfig.branch}/\${githubContentPath}\`;
+
+  return (
+    <DocsPage toc={[]} tableOfContent={{ enabled: false }} tableOfContentPopover={{ enabled: false }} footer={{ enabled: false }}>
+      <DocsTitle>{title}</DocsTitle>
+      <DocsDescription className="mb-0">{description}</DocsDescription>
+      <div className="mb-6 flex flex-row items-center gap-2 border-b pb-6">
+        <LLMCopyButton markdownUrl={markdownUrl} />
+        <ViewOptions markdownUrl={markdownUrl} githubUrl={githubUrl} />
+      </div>
+      <DocsBody>{children}</DocsBody>
+    </DocsPage>
+  );
+}
+`;
+    const result = await (0, shared_1.ensureFile)(target, content);
+    console.log(result === "created" ? `Created ${target}` : `Skipped ${target} (already exists)`);
+}
+async function addSidebarHistory(appRoot) {
+    const { basePath, contentRoot } = await (0, shared_1.getFumadocsSettings)(appRoot);
+    const packageJsonPath = (0, node_path_1.resolve)(appRoot, "package.json");
+    const packageJson = await (0, shared_1.loadJson)(packageJsonPath);
+    if (packageJson) {
+        const dependencies = packageJson.dependencies ?? {};
+        if (!dependencies["@chris-lally/fumadocs"]) {
+            dependencies["@chris-lally/fumadocs"] = "^0.1.0-alpha.1";
+            packageJson.dependencies = dependencies;
+            await (0, shared_1.ensureJsonFile)(packageJsonPath, packageJson);
+            console.log("Added dependency: @chris-lally/fumadocs");
+        }
+    }
+    const componentPath = (0, node_path_1.resolve)(appRoot, "src/components/sidebar/global-history-banner.tsx");
+    const componentContent = `"use client";
+
+import { SidebarHistoryBanner } from '@chris-lally/fumadocs';
+
+export function GlobalHistoryBanner() {
+  return <SidebarHistoryBanner basePath="${basePath}" storageKey="${contentRoot}-sidebar-history-v1" />;
+}
+`;
+    const result = await (0, shared_1.ensureFile)(componentPath, componentContent);
+    console.log(result === "created" ? `Created ${componentPath}` : `Skipped ${componentPath} (already exists)`);
+    const routeLayoutPath = (0, node_path_1.resolve)(appRoot, `src/app/${contentRoot}/layout.tsx`);
+    const docsLayoutPath = (0, node_path_1.resolve)(appRoot, "src/app/docs/layout.tsx");
+    const targetLayoutPath = (0, node_fs_1.existsSync)(routeLayoutPath) ? routeLayoutPath : docsLayoutPath;
+    if ((0, node_fs_1.existsSync)(targetLayoutPath)) {
+        let layout = await (0, promises_1.readFile)(targetLayoutPath, "utf8");
+        if (!layout.includes("GlobalHistoryBanner")) {
+            layout = `import { GlobalHistoryBanner } from '@/components/sidebar/global-history-banner';\n${layout}`;
+        }
+        if (!layout.includes("sidebar={{ banner: <GlobalHistoryBanner /> }}")) {
+            layout = layout.replace(/<DocsLayout([\s\S]*?)>/m, (match) => {
+                if (match.includes("sidebar={"))
+                    return match;
+                return match.replace(">", "\n      sidebar={{ banner: <GlobalHistoryBanner /> }}\n    >");
+            });
+        }
+        await (0, promises_1.writeFile)(targetLayoutPath, layout, "utf8");
+        console.log(`Updated layout with sidebar history banner: ${targetLayoutPath}`);
+    }
+    else {
+        console.log(`No src/app/${contentRoot}/layout.tsx or src/app/docs/layout.tsx found. Wire GlobalHistoryBanner manually in your DocsLayout sidebar.banner.`);
+    }
+}
+//# sourceMappingURL=fumadocs.js.map

package/dist/commands/add/fumadocs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fumadocs.js","sourceRoot":"","sources":["../../../src/commands/add/fumadocs.ts"],"names":[],"mappings":"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"}

package/dist/commands/{add.d.ts → add/index.d.ts}

@@ -1,2 +1 @@
 export declare function runAddCommand(args: string[]): Promise<void>;
-//# sourceMappingURL=add.d.ts.map

package/dist/commands/add/index.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAddCommand = runAddCommand;
+const db_1 = require("./db");
+const fumadocs_1 = require("./fumadocs");
+const shared_1 = require("./shared");
+const SUPPORTED_ITEMS = [
+    "fumadocs/section",
+    "fumadocs/page-shell",
+    "fumadocs/sidebar-history",
+    "db/local-postgres",
+    "db/master-migration",
+    "db/seed-script",
+];
+function addHelp() {
+    return [
+        "Usage:",
+        "  lally add <namespace/item> [--app <path>]",
+        "",
+        "Supported items:",
+        "  fumadocs/section         Add a root section under content/<contentRoot>",
+        "  fumadocs/page-shell      Add a notebook page shell component",
+        "  fumadocs/sidebar-history Add global sidebar history banner wiring",
+        "  db/local-postgres        Add local DB create/migrate/reset scripts",
+        "  db/master-migration      Add db/migrations/tables.sql scaffold",
+        "  db/seed-script           Add local seed script + package scripts",
+        "",
+        "Examples:",
+        "  lally add fumadocs/section --name handbook --app apps/web",
+        "  lally add fumadocs/page-shell --app apps/web",
+        "  lally add db/local-postgres --app apps/web",
+        "",
+        "Notes:",
+        "  - If run from monorepo root, pass --app.",
+        "  - Uses lally.config.json fumadocs.basePath/contentRoot when available.",
+    ].join("\n");
+}
+async function runAddCommand(args) {
+    const { item, flags } = (0, shared_1.parseArgs)(args);
+    if (!item || item === "--help" || item === "-h" || item === "help") {
+        console.log(addHelp());
+        if (!item || item === "--help" || item === "-h" || item === "help") {
+            return;
+        }
+    }
+    if (!item) {
+        console.error("Missing item name.");
+        console.error(addHelp());
+        process.exitCode = 1;
+        return;
+    }
+    if (!SUPPORTED_ITEMS.includes(item)) {
+        console.error(`Unsupported item: ${item}`);
+        console.error(addHelp());
+        process.exitCode = 1;
+        return;
+    }
+    const appFlag = (0, shared_1.getStringFlag)(flags, "app");
+    const appRoot = (0, shared_1.resolveAppRoot)(appFlag);
+    if (!appFlag && (0, shared_1.looksLikeMonorepoRoot)(process.cwd())) {
+        console.error("Current directory looks like a monorepo root, not an app directory.");
+        console.error("Use --app <path> (example: --app apps/web).");
+        process.exitCode = 1;
+        return;
+    }
+    if (!(0, shared_1.looksLikeAppDirectory)(appRoot)) {
+        console.error(`Target path does not look like an app directory: ${appRoot}`);
+        console.error("Expected package.json plus app markers like next.config.*, src/app, or content.");
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        if (item === "fumadocs/section") {
+            const name = (0, shared_1.getStringFlag)(flags, "name");
+            if (!name) {
+                console.error("Missing required flag: --name");
+                console.log("Usage: lally add fumadocs/section --name <section-name> [--app <path>]");
+                process.exitCode = 1;
+                return;
+            }
+            await (0, fumadocs_1.addFumadocsSection)(appRoot, name);
+            return;
+        }
+        if (item === "fumadocs/page-shell") {
+            await (0, fumadocs_1.addPageShell)(appRoot);
+            return;
+        }
+        if (item === "fumadocs/sidebar-history") {
+            await (0, fumadocs_1.addSidebarHistory)(appRoot);
+            return;
+        }
+        if (item === "db/local-postgres") {
+            await (0, db_1.addDbLocalPostgres)(appRoot);
+            return;
+        }
+        if (item === "db/master-migration") {
+            await (0, db_1.addDbMasterMigration)(appRoot);
+            return;
+        }
+        if (item === "db/seed-script") {
+            await (0, db_1.addDbSeedScript)(appRoot);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/add/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/add/index.ts"],"names":[],"mappings":";;AAmDA,sCAkFC;AArID,6BAAiF;AACjF,yCAAiF;AACjF,qCAMkB;AAUlB,MAAM,eAAe,GAAc;IACjC,kBAAkB;IAClB,qBAAqB;IACrB,0BAA0B;IAC1B,mBAAmB;IACnB,qBAAqB;IACrB,gBAAgB;CACjB,CAAC;AAEF,SAAS,OAAO;IACd,OAAO;QACL,QAAQ;QACR,6CAA6C;QAC7C,EAAE;QACF,kBAAkB;QAClB,2EAA2E;QAC3E,gEAAgE;QAChE,qEAAqE;QACrE,sEAAsE;QACtE,kEAAkE;QAClE,oEAAoE;QACpE,EAAE;QACF,WAAW;QACX,6DAA6D;QAC7D,gDAAgD;QAChD,8CAA8C;QAC9C,EAAE;QACF,QAAQ;QACR,4CAA4C;QAC5C,0EAA0E;KAC3E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAEM,KAAK,UAAU,aAAa,CAAC,IAAc;IAChD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAA,kBAAS,EAAC,IAAI,CAAC,CAAC;IAExC,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACnE,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YACnE,OAAO;QACT,CAAC;IACH,CAAC;IAED,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACpC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACzB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,IAAe,CAAC,EAAE,CAAC;QAC/C,OAAO,CAAC,KAAK,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC;QAC3C,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACzB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,IAAA,sBAAa,EAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,IAAA,uBAAc,EAAC,OAAO,CAAC,CAAC;IAExC,IAAI,CAAC,OAAO,IAAI,IAAA,8BAAqB,EAAC,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QACrD,OAAO,CAAC,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACrF,OAAO,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;QAC7D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,IAAI,CAAC,IAAA,8BAAqB,EAAC,OAAO,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,KAAK,CAAC,oDAAoD,OAAO,EAAE,CAAC,CAAC;QAC7E,OAAO,CAAC,KAAK,CAAC,iFAAiF,CAAC,CAAC;QACjG,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,IAAI,IAAI,KAAK,kBAAkB,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,IAAA,sBAAa,EAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC1C,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;gBAC/C,OAAO,CAAC,GAAG,CAAC,wEAAwE,CAAC,CAAC;gBACtF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;gBACrB,OAAO;YACT,CAAC;YACD,MAAM,IAAA,6BAAkB,EAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACxC,OAAO;QACT,CAAC;QAED,IAAI,IAAI,KAAK,qBAAqB,EAAE,CAAC;YACnC,MAAM,IAAA,uBAAY,EAAC,OAAO,CAAC,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,IAAI,IAAI,KAAK,0BAA0B,EAAE,CAAC;YACxC,MAAM,IAAA,4BAAiB,EAAC,OAAO,CAAC,CAAC;YACjC,OAAO;QACT,CAAC;QAED,IAAI,IAAI,KAAK,mBAAmB,EAAE,CAAC;YACjC,MAAM,IAAA,uBAAkB,EAAC,OAAO,CAAC,CAAC;YAClC,OAAO;QACT,CAAC;QAED,IAAI,IAAI,KAAK,qBAAqB,EAAE,CAAC;YACnC,MAAM,IAAA,yBAAoB,EAAC,OAAO,CAAC,CAAC;YACpC,OAAO;QACT,CAAC;QAED,IAAI,IAAI,KAAK,gBAAgB,EAAE,CAAC;YAC9B,MAAM,IAAA,oBAAe,EAAC,OAAO,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACvB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/commands/add/shared.d.ts

@@ -0,0 +1,25 @@
+export type ParsedArgs = {
+    item: string | undefined;
+    flags: Map<string, string | boolean>;
+};
+export type LallyConfig = {
+    fumadocs?: {
+        basePath?: string;
+        contentRoot?: string;
+    };
+};
+export declare function parseArgs(args: string[]): ParsedArgs;
+export declare function getStringFlag(flags: Map<string, string | boolean>, key: string): string | null;
+export declare function toTitleCase(segment: string): string;
+export declare function resolveAppRoot(rawAppPath: string | null): string;
+export declare function looksLikeMonorepoRoot(dir: string): boolean;
+export declare function looksLikeAppDirectory(dir: string): boolean;
+export declare function ensureFile(filePath: string, content: string): Promise<"created" | "skipped">;
+export declare function ensureJsonFile<T extends object>(filePath: string, value: T): Promise<void>;
+export declare function loadJson<T>(filePath: string): Promise<T | null>;
+export declare function normalizeBasePath(raw: string | undefined): string;
+export declare function normalizeContentRoot(raw: string | undefined): string;
+export declare function getFumadocsSettings(appRoot: string): Promise<{
+    basePath: string;
+    contentRoot: string;
+}>;