@podosoft/podokit 0.14.0 → 0.16.0

package/README.md

@@ -38,6 +38,7 @@ The `todo` template (`--template todo`) generates a working todo app (SvelteKit
 | `podo update [--apply]` | Preview (or apply) what a version update would change |
 | `podo eject <path…>` | Take ownership of a managed file so updates skip it |
 | `podo dev <action>` | Watch, inspect, execute in, or stop a container stack behind the shared `*.localhost` gateway |
+| `podo deploy <action>` | Plan, apply, verify, or roll back an exact-image Helm release |
 
 ## Usage
 
@@ -61,6 +62,9 @@ Generated projects include agent guidance for AI coding tools — an
 it, `.cursor`/`.github` pointers, and Claude Code skills under `.claude/skills/`.
 Modules extend `AGENTS.md` as you add them. Use `--no-ai` to skip.
 
+Fullstack projects also include a deployment skill under `.agents/skills/`
+with a Claude pointer under `.claude/skills/`.
+
 Examples:
 
 ```bash
@@ -101,6 +105,22 @@ podo update --apply  # apply it: clean updates are written, your edits are 3-way
 
 Files you own (routes, your components, shadcn UI) are never touched. See the
 [updating guide](https://github.com/podosoft-dev/podokit/blob/main/docs/updating.md).
+An exact path handed over with `podo eject` remains owned even if a module also
+declares it managed; if you later move or delete that file, update reports the
+missing owned path instead of recreating it.
+
+## Deploy an immutable release
+
+```bash
+podo deploy init --profile production --context production --host app.example.com
+podo deploy doctor --profile production
+podo deploy plan --profile production --release v1.2.3 --json
+```
+
+Apply and rollback require the exact confirmation hash from a fresh plan.
+PodoKit consumes an existing namespace and Secrets, runs migrations before the
+application rollout, and exposes only the SvelteKit web proxy. See the
+[deployment guide](https://github.com/podosoft-dev/podokit/blob/main/docs/deployment.md).
 
 ## What you get (`fullstack-nest-svelte`)
 

package/dist/add.d.ts

@@ -61,6 +61,10 @@ export interface ModuleManifest {
     managedOverrides?: string[];
     /** Idempotent path migrations applied by `podo update --apply`. */
     migrations?: ModuleMigration[];
+    /** Baseline files that must already exist before this module can be applied. */
+    requiredProjectFiles?: string[];
+    /** Stable source contracts that must be present in generated baseline files. */
+    requiredProjectContents?: Record<string, string[]>;
 }
 export interface PackageOverlay {
     dependencies?: Record<string, string>;

package/dist/add.js

@@ -88,6 +88,57 @@ function assertManifestVersion(name, manifest) {
         throw new Error(`Module "${name}" needs a newer PodoKit (manifest v${manifest.manifestVersion}, this CLI supports v${exports.SUPPORTED_MANIFEST_VERSION}). Update @podosoft/podokit.`);
     }
 }
+function assertRequiredProjectFiles(projectRoot, name, manifest) {
+    const contents = manifest.requiredProjectContents ?? {};
+    const required = [
+        ...(manifest.requiredProjectFiles ?? []),
+        ...Object.keys(contents),
+    ];
+    const invalid = required.find((path) => path.startsWith("/") ||
+        path.split("/").includes("..") ||
+        path.trim() === "");
+    if (invalid) {
+        throw new Error(`Module "${name}" declares an invalid required project file: ${invalid}.`);
+    }
+    const missing = required.filter((path) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(projectRoot, path)));
+    if (missing.length) {
+        throw new Error(`Module "${name}" requires a newer PodoKit project baseline. Run podo update --apply, then retry. Missing: ${missing.join(", ")}.`);
+    }
+    const invalidContract = Object.entries(contents).find(([, snippets]) => !Array.isArray(snippets) ||
+        snippets.length === 0 ||
+        snippets.some((snippet) => typeof snippet !== "string" || snippet.length === 0));
+    if (invalidContract) {
+        throw new Error(`Module "${name}" declares an invalid required project content contract: ${invalidContract[0]}.`);
+    }
+    const incompatible = Object.entries(contents)
+        .filter(([path, snippets]) => {
+        const source = (0, node_fs_1.readFileSync)((0, node_path_1.join)(projectRoot, path), "utf8");
+        return snippets.some((snippet) => !source.includes(snippet));
+    })
+        .map(([path]) => path);
+    if (incompatible.length) {
+        throw new Error(`Module "${name}" requires a newer PodoKit project baseline. Run podo update --apply, then retry. Incompatible: ${incompatible.join(", ")}.`);
+    }
+}
+function assertModuleGraphPrerequisites(projectRoot, module, modulesDir, visited = new Set(), requiredBy) {
+    if (visited.has(module))
+        return;
+    visited.add(module);
+    const resolved = resolveModule(module, modulesDir, projectRoot);
+    if (!resolved) {
+        if (requiredBy) {
+            throw new Error(`Module "${requiredBy}" requires unknown module "${module}".`);
+        }
+        const available = listModules(modulesDir, projectRoot).map((entry) => entry.name);
+        throw new Error(`Unknown module "${module}".${available.length ? ` Available: ${available.join(", ")}.` : ""}`);
+    }
+    const manifest = readModuleManifest(resolved.dir);
+    assertManifestVersion(module, manifest);
+    assertRequiredProjectFiles(projectRoot, module, manifest);
+    for (const required of manifest.requires ?? []) {
+        assertModuleGraphPrerequisites(projectRoot, required, modulesDir, visited, module);
+    }
+}
 /** List modules available to a project: the bundled ones under `modulesDir` plus,
  *  when `projectRoot` is given, any `@podosoft/podokit-module-*` packages installed
  *  in it. Bundled names take precedence on a clash. */
@@ -138,8 +189,13 @@ function appendEnv(projectRoot, lines) {
     const separator = current.endsWith("\n") ? "" : "\n";
     (0, node_fs_1.writeFileSync)(file, `${current}${separator}\n${missing.join("\n")}\n`);
 }
-/** Heuristic: is `module` already applied to the project? */
+/** Prefer the generation manifest as the authoritative installed-module list.
+ * Fall back to the legacy wiring heuristic only for projects without one. */
 function isApplied(projectRoot, modulesDir, module) {
+    const projectManifest = (0, lockfile_1.readManifest)(projectRoot);
+    if (projectManifest) {
+        return projectManifest.modules.some((entry) => entry.name === module);
+    }
     const moduleDir = resolveModuleDir(module, modulesDir, projectRoot);
     if (!moduleDir)
         return false;
@@ -157,6 +213,7 @@ function isApplied(projectRoot, modulesDir, module) {
  * and inject wiring at markers. Missing required modules are added first.
  */
 function addModule(options) {
+    assertModuleGraphPrerequisites(options.projectRoot, options.module, options.modulesDir);
     const previousLock = (0, lockfile_1.readFilesLock)(options.projectRoot);
     const cleanPaths = previousLock
         ? Object.entries(previousLock.files)
@@ -195,6 +252,7 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
     const moduleDir = resolved.dir;
     const manifest = readModuleManifest(moduleDir);
     assertManifestVersion(module, manifest);
+    assertRequiredProjectFiles(projectRoot, module, manifest);
     const requiredApps = new Set([manifest.targetApp, ...Object.keys(manifest.packageOverlays ?? {})]);
     const missingApp = [...requiredApps].find((app) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(projectRoot, "apps", app, "package.json")));
     if (missingApp) {

package/dist/create.js

@@ -10,7 +10,14 @@ const templates_1 = require("./templates");
 Object.defineProperty(exports, "DEFAULT_TEMPLATE", { enumerable: true, get: function () { return templates_1.DEFAULT_TEMPLATE; } });
 const lockfile_1 = require("./lockfile");
 /** AI agent guidance files, removed when scaffolding with `--no-ai`. */
-const AI_ARTIFACTS = ["AGENTS.md", "CLAUDE.md", ".claude", ".cursor", ".github/copilot-instructions.md"];
+const AI_ARTIFACTS = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".agents",
+    ".claude",
+    ".cursor",
+    ".github/copilot-instructions.md",
+];
 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) {

package/dist/deploy-profile.d.ts

@@ -0,0 +1,92 @@
+export type DependencyMode = "inCluster" | "external" | "disabled";
+export interface ResourceProfile {
+    cpuRequest: string;
+    cpuLimit: string;
+    memoryRequest: string;
+    memoryLimit: string;
+}
+export interface WorkloadProfile {
+    replicas: number;
+    resources: ResourceProfile;
+}
+export interface StatefulDependencyProfile {
+    mode: DependencyMode;
+    image: string;
+    secretName: string;
+    storageClassName: string;
+    storageSize: string;
+}
+export type RedisDependencyProfile = StatefulDependencyProfile;
+export interface ObjectStorageDependencyProfile extends StatefulDependencyProfile {
+    bucket: string;
+    clientImage: string;
+}
+export interface NamedSecretProfile {
+    name: string;
+    requiredKeys: string[];
+}
+export interface VerificationCheckProfile {
+    path: string;
+    expectedStatus: number;
+    expectedJson?: Record<string, string | number | boolean | null>;
+}
+export interface DeployProfileV1 {
+    schemaVersion: 1;
+    driver: "kubernetes-helm";
+    target: {
+        context: string;
+        clusterFingerprint: string;
+        namespace: string;
+        release: string;
+        createNamespace: false;
+    };
+    release: {
+        strategy: "shared-tag";
+        tagPattern: string;
+        apiRepository: string;
+        webRepository: string;
+    };
+    exposure: {
+        mode: "ingress" | "nodePort";
+        host: string;
+        ingressClassName: string;
+        tlsSecretName: string | null;
+    };
+    workloads: {
+        api: WorkloadProfile;
+        web: WorkloadProfile;
+        worker: WorkloadProfile | null;
+    };
+    dependencies: {
+        postgres: StatefulDependencyProfile;
+        redis: RedisDependencyProfile;
+        objectStorage: ObjectStorageDependencyProfile;
+    };
+    secrets: {
+        api: NamedSecretProfile;
+        web: NamedSecretProfile | null;
+        imagePull: string;
+    };
+    runtimeConfig: Record<string, string>;
+    verification: {
+        baseUrl: string;
+        checks: VerificationCheckProfile[];
+    };
+}
+export interface DeploymentProfileSummary {
+    name: string;
+    path: string;
+    profile: DeployProfileV1;
+}
+export declare function profileDirectory(projectRoot: string): string;
+export declare function profilePath(projectRoot: string, name: string): string;
+export declare function loadDeploymentProfile(projectRoot: string, name: string): DeployProfileV1;
+export declare function listDeploymentProfiles(projectRoot: string): DeploymentProfileSummary[];
+export interface InitializeDeploymentProfileOptions {
+    context: string;
+    clusterFingerprint: string;
+    host?: string;
+}
+export declare function initializeDeploymentProfile(projectRoot: string, name: string, options: InitializeDeploymentProfileOptions): DeploymentProfileSummary;
+export declare function assertReleaseTag(profile: DeployProfileV1, release: string): void;
+export declare function deploymentProfileDigest(profile: DeployProfileV1): string;