@podosoft/podokit 0.4.0 → 0.5.0

package/README.md

@@ -14,8 +14,8 @@ cp .env.example .env
 npm run dev
 ```
 
-- API: http://localhost:3000 (health at `/health`)
-- Web: http://localhost:5173
+- API: http://localhost:5002 (health at `/health`)
+- Web: http://localhost:5001
 
 When run in a terminal, `podo create` lists the templates with descriptions and asks which one (and which package manager) to use. Pass flags (or `--yes`) to skip the prompts.
 

package/dist/add.d.ts

@@ -19,6 +19,8 @@ export interface AddOptions {
     projectRoot: string;
     module: string;
     modulesDir: string;
+    /** PodoKit version stamped into the lockfile. Defaults to the CLI version. */
+    podokitVersion?: string;
 }
 export interface AddResult {
     module: string;

package/dist/add.js

@@ -5,6 +5,7 @@ exports.addModule = addModule;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
+const lockfile_1 = require("./lockfile");
 /** List modules available under `modulesDir` (each has a module.manifest.json). */
 function listModules(modulesDir) {
     if (!(0, node_fs_1.existsSync)(modulesDir))
@@ -56,7 +57,10 @@ function isApplied(projectRoot, modulesDir, module) {
  * and inject wiring at markers. Missing required modules are added first.
  */
 function addModule(options) {
-    return applyModule(options.projectRoot, options.module, options.modulesDir, new Set());
+    const result = applyModule(options.projectRoot, options.module, options.modulesDir, new Set());
+    // Record the module (and any auto-added requirements) and refresh the lock.
+    (0, lockfile_1.recordModules)(options.projectRoot, [...result.added, result.module], options.podokitVersion);
+    return result;
 }
 function applyModule(projectRoot, module, modulesDir, applied) {
     const moduleDir = (0, node_path_1.join)(modulesDir, module);

package/dist/assemble.d.ts

@@ -0,0 +1,14 @@
+import { type TemplateVars, type VfsTree } from "@podosoft/podokit-template-engine";
+/**
+ * Reconstruct a generated project in memory (no disk writes) from a template
+ * plus an ordered module list, mirroring `create` + `add`. `podo update` uses
+ * this to build the new-version tree and diff it against the working copy.
+ */
+export interface AssembleOptions {
+    templatesDir: string;
+    template: string;
+    answers: TemplateVars;
+    modules: string[];
+}
+/** Assemble the project tree for a template + ordered modules, in memory. */
+export declare function assembleProject(options: AssembleOptions): VfsTree;

package/dist/assemble.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assembleProject = assembleProject;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
+function readManifest(moduleDir) {
+    return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8"));
+}
+function textOf(tree, path) {
+    return String(tree.get(path)?.content ?? "");
+}
+function setText(tree, path, content) {
+    tree.set(path, { content, text: true });
+}
+function applyModuleToTree(tree, moduleDir, vars) {
+    const manifest = readManifest(moduleDir);
+    // 1) overlay files (module files override the base)
+    const filesDir = (0, node_path_1.join)(moduleDir, "files");
+    if ((0, node_fs_1.existsSync)(filesDir)) {
+        for (const [path, file] of (0, podokit_template_engine_1.renderTemplate)(filesDir, vars))
+            tree.set(path, file);
+    }
+    // 2) merge dependencies/scripts into the target app's package.json
+    if (manifest.dependencies || manifest.devDependencies || manifest.scripts) {
+        const pkgPath = `apps/${manifest.targetApp}/package.json`;
+        const base = JSON.parse(textOf(tree, pkgPath) || "{}");
+        const overlay = {};
+        if (manifest.dependencies)
+            overlay.dependencies = manifest.dependencies;
+        if (manifest.devDependencies)
+            overlay.devDependencies = manifest.devDependencies;
+        if (manifest.scripts)
+            overlay.scripts = manifest.scripts;
+        setText(tree, pkgPath, `${JSON.stringify((0, podokit_template_engine_1.mergePackageJson)(base, overlay), null, 2)}\n`);
+    }
+    // 3) append env example lines (deduped)
+    if (manifest.env?.length) {
+        const current = textOf(tree, ".env.example");
+        const existing = current.split("\n");
+        const missing = manifest.env.filter((line) => !existing.includes(line));
+        if (missing.length) {
+            const sep = current.endsWith("\n") ? "" : "\n";
+            setText(tree, ".env.example", `${current}${sep}\n${missing.join("\n")}\n`);
+        }
+    }
+    // 4) inject wiring at markers
+    for (const injection of manifest.inject ?? []) {
+        const target = injection.file;
+        setText(tree, target, (0, podokit_template_engine_1.insertAtMarker)(textOf(tree, target), injection.marker, injection.text));
+    }
+}
+/** Assemble the project tree for a template + ordered modules, in memory. */
+function assembleProject(options) {
+    const tree = (0, podokit_template_engine_1.renderTemplate)((0, node_path_1.join)(options.templatesDir, options.template), options.answers);
+    for (const mod of options.modules) {
+        applyModuleToTree(tree, (0, node_path_1.join)(options.templatesDir, "modules", mod), options.answers);
+    }
+    return tree;
+}

package/dist/create.d.ts

@@ -12,6 +12,8 @@ export interface CreateOptions {
     targetDir?: string;
     /** Package manager recorded in the generated project. Defaults to `npm`. */
     packageManager?: PackageManager;
+    /** PodoKit version stamped into the lockfile. Defaults to the CLI version. */
+    podokitVersion?: string;
 }
 export interface CreateResult {
     projectDir: string;

package/dist/create.js

@@ -8,6 +8,7 @@ const node_path_1 = require("node:path");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const templates_1 = require("./templates");
 Object.defineProperty(exports, "DEFAULT_TEMPLATE", { enumerable: true, get: function () { return templates_1.DEFAULT_TEMPLATE; } });
+const lockfile_1 = require("./lockfile");
 const NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-._]*[a-z0-9])?$/i;
 /** Validate a project name: no path separators, npm-friendly characters. */
 function assertValidName(name) {
@@ -41,5 +42,11 @@ function create(options) {
     }
     const vars = { projectName: name, packageManager };
     (0, podokit_template_engine_1.copyTemplate)(templateDir, projectDir, vars);
+    (0, lockfile_1.initLockfile)(projectDir, {
+        template,
+        packageManager,
+        answers: { projectName: name, packageManager },
+        version: options.podokitVersion,
+    });
     return { projectDir, packageManager, template };
 }

package/dist/eject.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Take ownership of PodoKit-managed files: flip their lock tier to `owned` so
+ * `podo update` skips them from then on (they show up only in `podo diff`).
+ * File-level and reversible by re-recording, unlike CRA's one-way eject.
+ */
+export interface EjectResult {
+    ejected: string[];
+    /** Paths not tracked in the lock (nothing to eject). */
+    unknown: string[];
+}
+export declare function eject(projectRoot: string, paths: string[]): EjectResult;

package/dist/eject.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eject = eject;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const lockfile_1 = require("./lockfile");
+const inspect_1 = require("./inspect");
+function eject(projectRoot, paths) {
+    const lock = (0, lockfile_1.readFilesLock)(projectRoot);
+    if (!lock)
+        throw new inspect_1.NotAProjectError();
+    const result = { ejected: [], unknown: [] };
+    for (const path of paths) {
+        const entry = lock.files[path];
+        if (!entry || !(0, node_fs_1.existsSync)((0, node_path_1.join)(projectRoot, path))) {
+            result.unknown.push(path);
+            continue;
+        }
+        if (entry.tier !== "owned") {
+            entry.tier = "owned";
+            result.ejected.push(path);
+        }
+    }
+    if (result.ejected.length)
+        (0, lockfile_1.writeFilesLock)(projectRoot, lock);
+    return result;
+}

package/dist/index.d.ts

@@ -6,6 +6,8 @@ interface ParsedArgs {
     template?: string;
     dir?: string;
     pm?: PackageManager;
+    from?: string;
+    apply: boolean;
     yes: boolean;
     help: boolean;
 }

package/dist/index.js

@@ -8,11 +8,19 @@ const create_1 = require("./create");
 const prompt_1 = require("./prompt");
 const templates_1 = require("./templates");
 const add_1 = require("./add");
+const inspect_1 = require("./inspect");
+const update_1 = require("./update");
+const eject_1 = require("./eject");
 const HELP = `podo — PodoKit project generator
 
 Usage:
   podo create <name> [options]
   podo add <module>
+  podo status              Show version, modules, file tiers, and local edits
+  podo diff                List PodoKit-managed files you have edited
+  podo doctor              Check framework versions against supported ranges
+  podo update [--apply]    Preview (or apply) what a version update would change
+  podo eject <path...>     Take ownership of managed files (update skips them)
 
 Options:
   --template <t> Template to scaffold (see below)
@@ -30,7 +38,7 @@ Example:
   cd my-app && npx @podosoft/podokit add auth
 `;
 function parseArgs(argv) {
-    const parsed = { help: false, yes: false };
+    const parsed = { help: false, yes: false, apply: false };
     const positionals = [];
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -40,12 +48,18 @@ function parseArgs(argv) {
         else if (arg === "-y" || arg === "--yes") {
             parsed.yes = true;
         }
+        else if (arg === "--apply") {
+            parsed.apply = true;
+        }
         else if (arg === "--template") {
             parsed.template = argv[++i];
         }
         else if (arg === "--dir") {
             parsed.dir = argv[++i];
         }
+        else if (arg === "--from") {
+            parsed.from = argv[++i];
+        }
         else if (arg === "--pm") {
             parsed.pm = argv[++i];
         }
@@ -93,6 +107,113 @@ async function main(argv) {
         }
         return;
     }
+    if (args.command === "status") {
+        try {
+            const s = (0, inspect_1.status)(process.cwd());
+            const tiers = `managed ${s.tiers.managed}, assembled ${s.tiers.assembled}, owned ${s.tiers.owned}`;
+            process.stdout.write(`PodoKit ${s.podokitVersion}  (template: ${s.template}, ${s.packageManager})\n` +
+                `Modules: ${s.modules.length ? s.modules.join(", ") : "(none)"}\n` +
+                `Files:   ${tiers}\n` +
+                `Edited:  ${s.drifted.length} managed file(s)${s.missing.length ? `, ${s.missing.length} missing` : ""}\n` +
+                (s.drifted.length ? s.drifted.map((f) => `  ~ ${f}`).join("\n") + "\n" : ""));
+        }
+        catch (err) {
+            fail(err.message);
+        }
+        return;
+    }
+    if (args.command === "diff") {
+        try {
+            const { drifted, missing } = (0, inspect_1.diff)(process.cwd());
+            if (!drifted.length && !missing.length) {
+                process.stdout.write("No local edits to PodoKit-managed files.\n");
+            }
+            else {
+                process.stdout.write([...drifted.map((f) => `edited   ${f}`), ...missing.map((f) => `missing  ${f}`)].join("\n") + "\n");
+            }
+        }
+        catch (err) {
+            fail(err.message);
+        }
+        return;
+    }
+    if (args.command === "doctor") {
+        try {
+            const findings = (0, inspect_1.doctor)(process.cwd());
+            if (!findings.length) {
+                process.stdout.write("No known frameworks found to check.\n");
+            }
+            else {
+                for (const f of findings) {
+                    const mark = f.ok ? "ok  " : "WARN";
+                    process.stdout.write(`${mark} ${f.package} ${f.installed} (supported: ${f.supported})\n`);
+                }
+            }
+            if (findings.some((f) => !f.ok)) {
+                process.stdout.write("\nSome frameworks are outside the supported range; @podosoft/* extensions may not match.\n");
+            }
+        }
+        catch (err) {
+            fail(err.message);
+        }
+        return;
+    }
+    if (args.command === "update") {
+        const templatesDir = (0, node_path_1.join)(__dirname, "templates");
+        try {
+            if (args.apply) {
+                const result = (0, update_1.applyUpdate)(process.cwd(), templatesDir, { oldTemplatesDir: args.from });
+                process.stdout.write(`Applied: ${result.written.length} written, ${result.removed.length} removed, ` +
+                    `${result.merged.length} merged, ${result.conflicts.length} conflict.\n`);
+                if (result.conflicts.length) {
+                    process.stdout.write("\nResolve the following, then commit:\n" +
+                        result.conflicts.map((f) => `  ${f}`).join("\n") +
+                        "\n");
+                }
+                return;
+            }
+            const plan = (0, update_1.planUpdate)(process.cwd(), templatesDir);
+            const counts = (0, update_1.summarize)(plan);
+            const shown = plan.changes.filter((c) => c.action !== "up-to-date" && c.action !== "skip");
+            process.stdout.write(`podo update ${plan.fromVersion} -> ${plan.toVersion}  (template: ${plan.template}; modules: ${plan.modules.join(", ") || "none"})\n\n`);
+            if (!shown.length) {
+                process.stdout.write("Everything is up to date.\n");
+            }
+            else {
+                for (const c of shown) {
+                    process.stdout.write(`  ${c.action.padEnd(9)} ${c.path}  (${c.note})\n`);
+                }
+                process.stdout.write(`\n${counts.update} update, ${counts.add} add, ${counts.remove} remove, ${counts.conflict} conflict. ` +
+                    `Dry-run — nothing was written. Re-run with --apply to write (use --from <dir> for a 3-way merge).\n`);
+            }
+        }
+        catch (err) {
+            fail(err.message);
+        }
+        return;
+    }
+    if (args.command === "eject") {
+        const targets = argv.filter((a) => !a.startsWith("-")).slice(1);
+        if (!targets.length) {
+            fail("Usage: podo eject <path...>");
+        }
+        try {
+            const result = (0, eject_1.eject)(process.cwd(), targets);
+            if (result.ejected.length) {
+                process.stdout.write(`Ejected (now owned): ${result.ejected.join(", ")}\n`);
+            }
+            if (result.unknown.length) {
+                process.stdout.write(`Not tracked, skipped: ${result.unknown.join(", ")}\n`);
+            }
+            if (!result.ejected.length && !result.unknown.length) {
+                process.stdout.write("Nothing to eject (already owned).\n");
+            }
+        }
+        catch (err) {
+            fail(err.message);
+        }
+        return;
+    }
     if (args.command !== "create") {
         fail(`Unknown command "${args.command}". Run "podo --help".`);
     }

package/dist/inspect.d.ts

@@ -0,0 +1,43 @@
+import { type Tier } from "./lockfile";
+/**
+ * Read-only project inspection for `podo status`, `podo diff`, and
+ * `podo doctor`. None of these write to disk.
+ */
+export interface StatusReport {
+    podokitVersion: string;
+    template: string;
+    packageManager: string;
+    modules: string[];
+    tiers: Record<Tier, number>;
+    drifted: string[];
+    missing: string[];
+}
+export declare class NotAProjectError extends Error {
+    constructor();
+}
+export declare function status(projectRoot: string): StatusReport;
+/** Managed/assembled files the user has edited or deleted since generation. */
+export declare function diff(projectRoot: string): {
+    drifted: string[];
+    missing: string[];
+};
+/** Framework version-compatibility check. See ADR-0008 (4-layer defense). */
+export interface DoctorFinding {
+    package: string;
+    installed: string;
+    supported: string;
+    ok: boolean;
+}
+/**
+ * Known-good framework ranges for the current PodoKit line. A generated app may
+ * bump these itself; doctor warns when it moves outside the supported range so
+ * `@podosoft/*` extensions still match.
+ */
+export declare const SUPPORTED_FRAMEWORKS: Record<string, {
+    app: "api" | "web";
+    range: string;
+    majors: number[];
+}>;
+/** Parse the leading major from a semver range like `^11.1.0` or `>=1.6.23 <1.7`. */
+export declare function leadingMajor(range: string): number | null;
+export declare function doctor(projectRoot: string): DoctorFinding[];

package/dist/inspect.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_FRAMEWORKS = exports.NotAProjectError = void 0;
+exports.status = status;
+exports.diff = diff;
+exports.leadingMajor = leadingMajor;
+exports.doctor = doctor;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const lockfile_1 = require("./lockfile");
+class NotAProjectError extends Error {
+    constructor() {
+        super("No .podokit/manifest.json found. Run inside a project created by `podo create`.");
+        this.name = "NotAProjectError";
+    }
+}
+exports.NotAProjectError = NotAProjectError;
+function status(projectRoot) {
+    const manifest = (0, lockfile_1.readManifest)(projectRoot);
+    const lock = (0, lockfile_1.readFilesLock)(projectRoot);
+    if (!manifest || !lock)
+        throw new NotAProjectError();
+    const tiers = { managed: 0, assembled: 0, owned: 0 };
+    for (const entry of Object.values(lock.files))
+        tiers[entry.tier] += 1;
+    const { drifted, missing } = (0, lockfile_1.computeDrift)(projectRoot);
+    return {
+        podokitVersion: manifest.podokitVersion,
+        template: manifest.template,
+        packageManager: manifest.packageManager,
+        modules: manifest.modules.map((m) => m.name),
+        tiers,
+        drifted,
+        missing,
+    };
+}
+/** Managed/assembled files the user has edited or deleted since generation. */
+function diff(projectRoot) {
+    if (!(0, lockfile_1.readManifest)(projectRoot))
+        throw new NotAProjectError();
+    return (0, lockfile_1.computeDrift)(projectRoot);
+}
+/**
+ * Known-good framework ranges for the current PodoKit line. A generated app may
+ * bump these itself; doctor warns when it moves outside the supported range so
+ * `@podosoft/*` extensions still match.
+ */
+exports.SUPPORTED_FRAMEWORKS = {
+    "@nestjs/core": { app: "api", range: "^11", majors: [11] },
+    "better-auth": { app: "api", range: ">=1.6.23 <1.7", majors: [1] },
+    svelte: { app: "web", range: "^5", majors: [5] },
+};
+function declaredVersion(projectRoot, app, pkg) {
+    const file = (0, node_path_1.join)(projectRoot, "apps", app, "package.json");
+    if (!(0, node_fs_1.existsSync)(file))
+        return null;
+    const json = JSON.parse((0, node_fs_1.readFileSync)(file, "utf8"));
+    return json.dependencies?.[pkg] ?? json.devDependencies?.[pkg] ?? null;
+}
+/** Parse the leading major from a semver range like `^11.1.0` or `>=1.6.23 <1.7`. */
+function leadingMajor(range) {
+    const match = range.match(/(\d+)\./);
+    return match ? Number(match[1]) : null;
+}
+function doctor(projectRoot) {
+    if (!(0, lockfile_1.readManifest)(projectRoot))
+        throw new NotAProjectError();
+    const findings = [];
+    for (const [pkg, spec] of Object.entries(exports.SUPPORTED_FRAMEWORKS)) {
+        const installed = declaredVersion(projectRoot, spec.app, pkg);
+        if (installed === null)
+            continue; // package not in this app
+        const major = leadingMajor(installed);
+        findings.push({
+            package: pkg,
+            installed,
+            supported: spec.range,
+            ok: major !== null && spec.majors.includes(major),
+        });
+    }
+    return findings;
+}

package/dist/lockfile.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The generation lockfile (`.podokit/`) records how a project was assembled so
+ * `podo update` can rebuild the same inputs and detect user edits. See
+ * ADR-0009 (update mechanism) and ADR-0010 (ownership model).
+ */
+export declare const LOCK_SCHEMA_VERSION = 1;
+/** File ownership tier. See ADR-0010. */
+export type Tier = "managed" | "assembled" | "owned";
+export interface ManifestModule {
+    name: string;
+    /** Application order; preserves layered injection determinism. */
+    order: number;
+    /** PodoKit version that applied the module. */
+    addedWith: string;
+}
+export interface PodokitManifest {
+    schemaVersion: number;
+    podokitVersion: string;
+    template: string;
+    packageManager: string;
+    /** Render vars / prompt answers, replayed on update (copier-style). */
+    answers: Record<string, string>;
+    modules: ManifestModule[];
+    /** Globs whose files are user-owned and never touched by update. */
+    ownedGlobs: string[];
+}
+export interface FileEntry {
+    tier: Tier;
+    /** Hash of the exact bytes PodoKit last wrote; user-edit detector. */
+    outHash: string;
+}
+export interface FilesLock {
+    schemaVersion: number;
+    files: Record<string, FileEntry>;
+}
+/** Default user-owned globs seeded into a new project. See ADR-0010. */
+export declare const DEFAULT_OWNED_GLOBS: string[];
+export declare function manifestPath(projectRoot: string): string;
+export declare function filesLockPath(projectRoot: string): string;
+export declare function readManifest(projectRoot: string): PodokitManifest | null;
+export declare function writeManifest(projectRoot: string, manifest: PodokitManifest): void;
+export declare function writeFilesLock(projectRoot: string, lock: FilesLock): void;
+/** Read the PodoKit CLI's own version to stamp into the manifest. */
+export declare function podokitVersion(): string;
+/** Match a POSIX relative path against a simple glob supporting `*` and `**`. */
+export declare function matchGlob(path: string, glob: string): boolean;
+/** Classify a file's ownership tier. See ADR-0010 priority order. */
+export declare function classifyTier(relPath: string, content: string | Buffer, ownedGlobs: string[]): Tier;
+/** List project files as POSIX-relative paths, skipping generated/vendored dirs. */
+export declare function walkFiles(projectRoot: string, prefix?: string): string[];
+/** Recompute the files.lock by hashing and classifying every project file. */
+export declare function computeFilesLock(projectRoot: string, ownedGlobs: string[]): FilesLock;
+export declare function readFilesLock(projectRoot: string): FilesLock | null;
+export interface Drift {
+    /** Managed/assembled files whose content differs from what PodoKit wrote. */
+    drifted: string[];
+    /** Locked files that no longer exist on disk. */
+    missing: string[];
+}
+/**
+ * Compare the current disk against the lock: report managed/assembled files the
+ * user has edited (hash mismatch) or deleted. Owned files are never reported —
+ * they belong to the user. Returns empty drift when there is no lock.
+ */
+export declare function computeDrift(projectRoot: string): Drift;
+export interface InitLockOptions {
+    template: string;
+    packageManager: string;
+    answers: Record<string, string>;
+    version?: string;
+    ownedGlobs?: string[];
+}
+/** Write the initial `.podokit/` lockfile for a freshly created project. */
+export declare function initLockfile(projectRoot: string, options: InitLockOptions): void;
+/**
+ * Record applied modules in the manifest and recompute the files.lock. Modules
+ * already present are left in place (idempotent); the lock always reflects disk.
+ * No-op on projects without a manifest (pre-lockfile projects; see `podo adopt`).
+ */
+export declare function recordModules(projectRoot: string, moduleNames: string[], version?: string): void;