kozou 0.0.2 → 0.1.1

package/dist/commands/inspect.js

@@ -0,0 +1,47 @@
+// `kozou inspect` command implementation.
+//
+// Pipeline:
+//   1. Load the kozou.config.yaml (or fall back to defaults).
+//   2. Introspect the target Postgres schema (@kozou/introspect).
+//   3. Optionally load UI hints (@kozou/core.loadUIHints).
+//   4. Build a SchemaContext (@kozou/core.buildSchemaContext).
+//   5. Serialize to JSON or YAML and write to stdout or a file.
+//
+// See Kozou v0.1 design spec §9.1.
+import { writeFile } from 'node:fs/promises';
+import { stringify as stringifyYAML } from 'yaml';
+import { buildSchemaContext, loadUIHints } from '@kozou/core';
+import { introspect } from '@kozou/introspect';
+import { loadConfig } from '../config.js';
+export async function inspectCommand(opts = {}) {
+    const format = opts.format ?? 'json';
+    const output = opts.output ?? '-';
+    if (format !== 'json' && format !== 'yaml') {
+        throw new Error(`kozou inspect: invalid --format "${format}" (expected "json" or "yaml")`);
+    }
+    const config = await loadConfig({ path: opts.config });
+    const raw = await introspect({
+        connection: config.database.url,
+        schemas: config.database.schemas,
+    });
+    let uiHints;
+    if (config.uiHints.path !== null && config.uiHints.path !== '') {
+        try {
+            uiHints = await loadUIHints(config.uiHints.path);
+        }
+        catch (err) {
+            // UI hints are optional; warn but continue without them.
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[kozou inspect] could not load UI hints: ${message}\n`);
+        }
+    }
+    const ctx = await buildSchemaContext({ raw, uiHints });
+    const serialized = format === 'yaml' ? stringifyYAML(ctx) : JSON.stringify(ctx, null, 2);
+    const payload = serialized.endsWith('\n') ? serialized : serialized + '\n';
+    if (output === '-') {
+        process.stdout.write(payload);
+        return;
+    }
+    await writeFile(output, payload, 'utf8');
+}
+//# sourceMappingURL=inspect.js.map

package/dist/commands/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/commands/inspect.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,EAAE;AACF,YAAY;AACZ,8DAA8D;AAC9D,kEAAkE;AAClE,2DAA2D;AAC3D,+DAA+D;AAC/D,gEAAgE;AAChE,EAAE;AACF,mCAAmC;AAEnC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAW1C,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAuB,EAAE;IAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC;IAClC,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,oCAAoC,MAAM,+BAA+B,CAAC,CAAC;IAC7F,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAEvD,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC;QAC3B,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG;QAC/B,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO;KACjC,CAAC,CAAC;IAEH,IAAI,OAA4B,CAAC;IACjC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QAC/D,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,yDAAyD;YACzD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4CAA4C,OAAO,IAAI,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACzF,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,GAAG,IAAI,CAAC;IAE3E,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,MAAM,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,9 @@
+export type McpOptions = {
+    stdio?: boolean;
+    http?: boolean;
+    port?: number;
+    host?: string;
+    config?: string;
+};
+export declare function mcpCommand(opts?: McpOptions): Promise<void>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/commands/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,wBAAsB,UAAU,CAAC,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBrE"}

package/dist/commands/mcp.js

@@ -0,0 +1,29 @@
+// `kozou mcp` command implementation.
+//
+// --stdio: spins up the @kozou/mcp server with a stdio transport, reading
+//   connection details from kozou.config.yaml / environment.
+// --http: spins up the @kozou/mcp server with the Streamable HTTP
+//   transport (Kozou v0.1 spec §7.1), binding to localhost by default and
+//   exposing POST /admin/refresh for cache invalidation (§7.5).
+//
+// See Kozou v0.1 design spec §9.1 and §7.
+import { SchemaCache, startHttpServer, startStdioServer } from '@kozou/mcp';
+import { loadConfig } from '../config.js';
+export async function mcpCommand(opts = {}) {
+    const config = await loadConfig({ path: opts.config });
+    const cache = new SchemaCache({
+        connection: config.database.url,
+        schemas: config.database.schemas,
+        ttlMs: config.cache.ttlMs,
+    });
+    if (opts.http === true) {
+        await startHttpServer(cache, {
+            port: opts.port,
+            host: opts.host,
+            logPrefix: '[kozou mcp]',
+        });
+        return;
+    }
+    await startStdioServer(cache, { logPrefix: '[kozou mcp]' });
+}
+//# sourceMappingURL=mcp.js.map

package/dist/commands/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,0EAA0E;AAC1E,6DAA6D;AAC7D,kEAAkE;AAClE,0EAA0E;AAC1E,gEAAgE;AAChE,EAAE;AACF,0CAA0C;AAE1C,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAU1C,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAmB,EAAE;IACpD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAEvD,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC;QAC5B,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG;QAC/B,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO;QAChC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK;KAC1B,CAAC,CAAC;IAEH,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,eAAe,CAAC,KAAK,EAAE;YAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS,EAAE,aAAa;SACzB,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,MAAM,gBAAgB,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC;AAC9D,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+declare const configSchema: z.ZodObject<{
+    database: z.ZodObject<{
+        url: z.ZodString;
+        schemas: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    server: z.ZodPrefault<z.ZodObject<{
+        ui: z.ZodPrefault<z.ZodObject<{
+            port: z.ZodDefault<z.ZodNumber>;
+            host: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+        mcp: z.ZodPrefault<z.ZodObject<{
+            http: z.ZodPrefault<z.ZodObject<{
+                port: z.ZodDefault<z.ZodNumber>;
+                host: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>;
+            stdio: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    adapter: z.ZodPrefault<z.ZodObject<{
+        type: z.ZodDefault<z.ZodLiteral<"postgrest">>;
+        url: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    uiHints: z.ZodPrefault<z.ZodObject<{
+        path: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    cache: z.ZodPrefault<z.ZodObject<{
+        ttlMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type KozouConfig = z.infer<typeof configSchema>;
+export type KozouConfigIssue = {
+    path: string;
+    message: string;
+};
+export declare class KozouConfigError extends Error {
+    readonly issues: KozouConfigIssue[];
+    readonly filePath: string | null;
+    constructor(message: string, filePath: string | null, issues: KozouConfigIssue[]);
+}
+export type LoadConfigOptions = {
+    /** Path to kozou.config.yaml. Default: ./kozou.config.yaml relative to cwd. */
+    path?: string;
+    /** Environment variables for ${VAR} expansion. Default: process.env. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * If true, do not read any file from disk; only honor explicit options and
+     * environment variables. Useful for unit tests.
+     */
+    skipFile?: boolean;
+};
+export declare function loadConfig(opts?: LoadConfigOptions): Promise<KozouConfig>;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+DxB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMhB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAIvD,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;gBACrB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE;CAMjF;AAMD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AA2DF,wBAAsB,UAAU,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,WAAW,CAAC,CA2CnF"}

package/dist/config.js

@@ -0,0 +1,178 @@
+// kozou.config.yaml loader.
+//
+// Reads the YAML config file, expands ${VAR} / ${VAR:-default} placeholders
+// against the process environment, fills in defaults, and validates the
+// result with zod. Every field has a default so kozou can run with only the
+// DATABASE_URL environment variable set, per the Kozou v0.1 design spec §9.2.
+//
+// A literal `$$` escapes to a single `$`, so `$${VAR}` produces the literal
+// text `${VAR}` instead of expanding it. Expansion is single-level by design:
+// a value substituted from the environment is never re-scanned, so a secret
+// that legitimately contains `${...}` (e.g. inside a DATABASE_URL password) is
+// preserved rather than mistaken for a placeholder. See expandEnvVars below.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+import { parse as parseYAML } from 'yaml';
+import { z } from 'zod';
+// ---- Schema ---------------------------------------------------------------
+// Nested sections use `.prefault({})` rather than `.default({})`: in zod 4
+// `.default(v)` short-circuits to `v` as-is when the input is undefined (so
+// it would need the fully-populated object), whereas `.prefault(v)` feeds
+// `v` back through the schema so each field's own `.default(...)` still
+// applies. `.prefault({})` therefore reproduces the zod 3 behaviour of
+// "absent section -> object filled entirely from inner defaults".
+const uiServerSchema = z
+    .object({
+    port: z.number().int().min(0).max(65_535).default(3333),
+    host: z.string().min(1).default('0.0.0.0'),
+})
+    .prefault({});
+const mcpHttpServerSchema = z
+    .object({
+    port: z.number().int().min(0).max(65_535).default(3334),
+    host: z.string().min(1).default('0.0.0.0'),
+})
+    .prefault({});
+const mcpServerSchema = z
+    .object({
+    http: mcpHttpServerSchema,
+    stdio: z.boolean().default(false),
+})
+    .prefault({});
+const serverSchema = z
+    .object({
+    ui: uiServerSchema,
+    mcp: mcpServerSchema,
+})
+    .prefault({});
+const adapterSchema = z
+    .object({
+    type: z.literal('postgrest').default('postgrest'),
+    url: z.string().min(1).default('http://postgrest:3000'),
+})
+    .prefault({});
+const uiHintsSchema = z
+    .object({
+    path: z.string().nullable().default(null),
+})
+    .prefault({});
+const cacheSchema = z
+    .object({
+    ttlMs: z.number().int().min(0).default(60_000),
+})
+    .prefault({});
+const databaseSchema = z.object({
+    url: z.string().min(1, 'database.url is required (set DATABASE_URL or kozou.config.yaml)'),
+    schemas: z.array(z.string().min(1)).default(['public']),
+});
+const configSchema = z.object({
+    database: databaseSchema,
+    server: serverSchema,
+    adapter: adapterSchema,
+    uiHints: uiHintsSchema,
+    cache: cacheSchema,
+});
+export class KozouConfigError extends Error {
+    issues;
+    filePath;
+    constructor(message, filePath, issues) {
+        super(message);
+        this.name = 'KozouConfigError';
+        this.filePath = filePath;
+        this.issues = issues;
+    }
+}
+// ---- Loader --------------------------------------------------------------
+const DEFAULT_CONFIG_PATH = 'kozou.config.yaml';
+// Matches either an escaped `$$` (which becomes a literal `$`) or a
+// `${VAR}` / `${VAR:-default}` placeholder. `$$` is listed first so the
+// alternation consumes it before the placeholder branch can see a stray `$`.
+const ENV_TOKEN_RE = /\$\$|\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+function expandEnvVars(value, env) {
+    if (typeof value === 'string') {
+        return value.replace(ENV_TOKEN_RE, (match, name, fallback) => {
+            // `$$` -> literal `$`. So `$${VAR}` yields the literal `${VAR}`:
+            // the trailing `{VAR}` is left untouched because it no longer has
+            // a `$` prefix to start a placeholder.
+            if (match === '$$')
+                return '$';
+            // Otherwise `match` is a `${...}` placeholder and `name` is its
+            // (always-present) variable name. The substituted value is taken
+            // verbatim and never re-scanned (single-level expansion), so a
+            // value containing `${...}` is preserved as-is.
+            const v = env[name];
+            if (v !== undefined)
+                return v;
+            if (fallback !== undefined)
+                return fallback;
+            return '';
+        });
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => expandEnvVars(v, env));
+    }
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = expandEnvVars(v, env);
+        }
+        return out;
+    }
+    return value;
+}
+function injectDatabaseUrlFromEnv(raw, env) {
+    if (raw === null || typeof raw !== 'object')
+        return raw;
+    const obj = raw;
+    const envUrl = env.DATABASE_URL;
+    if (envUrl === undefined || envUrl === '')
+        return obj;
+    const existing = obj.database;
+    if (existing === undefined) {
+        return { ...obj, database: { url: envUrl } };
+    }
+    if (existing !== null && typeof existing === 'object') {
+        const db = existing;
+        if (db.url === undefined || db.url === '') {
+            return { ...obj, database: { ...db, url: envUrl } };
+        }
+    }
+    return obj;
+}
+export async function loadConfig(opts = {}) {
+    const env = opts.env ?? process.env;
+    const requestedPath = opts.path ?? DEFAULT_CONFIG_PATH;
+    const absPath = isAbsolute(requestedPath)
+        ? requestedPath
+        : resolve(process.cwd(), requestedPath);
+    let raw = {};
+    let fileLoaded = null;
+    if (!opts.skipFile && existsSync(absPath)) {
+        const content = await readFile(absPath, 'utf8');
+        try {
+            raw = parseYAML(content) ?? {};
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new KozouConfigError(`Failed to parse kozou config: ${message}`, absPath, [{ path: '<yaml>', message }]);
+        }
+        fileLoaded = absPath;
+    }
+    // Fall back to DATABASE_URL env if database.url is not set in the file.
+    const withDbDefault = injectDatabaseUrlFromEnv(raw, env);
+    const expanded = expandEnvVars(withDbDefault, env);
+    try {
+        return configSchema.parse(expanded);
+    }
+    catch (err) {
+        if (err instanceof z.ZodError) {
+            throw new KozouConfigError(`Invalid kozou config: ${err.issues.length} issue(s)`, fileLoaded, err.issues.map((i) => ({
+                path: i.path.join('.') || '<root>',
+                message: i.message,
+            })));
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,EAAE;AACF,4EAA4E;AAC5E,wEAAwE;AACxE,4EAA4E;AAC5E,8EAA8E;AAC9E,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,4EAA4E;AAC5E,+EAA+E;AAC/E,6EAA6E;AAE7E,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8EAA8E;AAE9E,2EAA2E;AAC3E,4EAA4E;AAC5E,0EAA0E;AAC1E,wEAAwE;AACxE,uEAAuE;AACvE,kEAAkE;AAElE,MAAM,cAAc,GAAG,CAAC;KACrB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IACvD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;CAC3C,CAAC;KACD,QAAQ,CAAC,EAAE,CAAC,CAAC;AAEhB,MAAM,mBAAmB,GAAG,CAAC;KAC1B,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IACvD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;CAC3C,CAAC;KACD,QAAQ,CAAC,EAAE,CAAC,CAAC;AAEhB,MAAM,eAAe,GAAG,CAAC;KACtB,MAAM,CAAC;IACN,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CAClC,CAAC;KACD,QAAQ,CAAC,EAAE,CAAC,CAAC;AAEhB,MAAM,YAAY,GAAG,CAAC;KACnB,MAAM,CAAC;IACN,EAAE,EAAE,cAAc;IAClB,GAAG,EAAE,eAAe;CACrB,CAAC;KACD,QAAQ,CAAC,EAAE,CAAC,CAAC;AAEhB,MAAM,aAAa,GAAG,CAAC;KACpB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IACjD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,uBAAuB,CAAC;CACxD,CAAC;KACD,QAAQ,CAAC,EAAE,CAAC,CAAC;AAEhB,MAAM,aAAa,GAAG,CAAC;KACpB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CAC1C,CAAC;KACD,QAAQ,CAAC,EAAE,CAAC,CAAC;AAEhB,MAAM,WAAW,GAAG,CAAC;KAClB,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;CAC/C,CAAC;KACD,QAAQ,CAAC,EAAE,CAAC,CAAC;AAEhB,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,kEAAkE,CAAC;IAC1F,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC;CACxD,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,QAAQ,EAAE,cAAc;IACxB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,aAAa;IACtB,OAAO,EAAE,aAAa;IACtB,KAAK,EAAE,WAAW;CACnB,CAAC,CAAC;AAQH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,MAAM,CAAqB;IAC3B,QAAQ,CAAgB;IACjC,YAAY,OAAe,EAAE,QAAuB,EAAE,MAA0B;QAC9E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,6EAA6E;AAE7E,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AAchD,oEAAoE;AACpE,wEAAwE;AACxE,6EAA6E;AAC7E,MAAM,YAAY,GAAG,oDAAoD,CAAC;AAE1E,SAAS,aAAa,CAAC,KAAc,EAAE,GAAsB;IAC3D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,OAAO,CAClB,YAAY,EACZ,CAAC,KAAK,EAAE,IAAwB,EAAE,QAAiB,EAAE,EAAE;YACrD,iEAAiE;YACjE,kEAAkE;YAClE,uCAAuC;YACvC,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,GAAG,CAAC;YAC/B,gEAAgE;YAChE,iEAAiE;YACjE,+DAA+D;YAC/D,gDAAgD;YAChD,MAAM,CAAC,GAAG,GAAG,CAAC,IAAc,CAAC,CAAC;YAC9B,IAAI,CAAC,KAAK,SAAS;gBAAE,OAAO,CAAC,CAAC;YAC9B,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,QAAQ,CAAC;YAC5C,OAAO,EAAE,CAAC;QACZ,CAAC,CACF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YACtE,GAAG,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,wBAAwB,CAAC,GAAY,EAAE,GAAsB;IACpE,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACxD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC;IAChC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,GAAG,CAAC;IAEtD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;IAC9B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,EAAE,GAAG,GAAG,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC;IAC/C,CAAC;IACD,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACtD,MAAM,EAAE,GAAG,QAAmC,CAAC;QAC/C,IAAI,EAAE,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,EAAE,CAAC;YAC1C,OAAO,EAAE,GAAG,GAAG,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC;QACtD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAA0B,EAAE;IAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,IAAI,mBAAmB,CAAC;IACvD,MAAM,OAAO,GAAG,UAAU,CAAC,aAAa,CAAC;QACvC,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,CAAC,CAAC;IAE1C,IAAI,GAAG,GAAY,EAAE,CAAC;IACtB,IAAI,UAAU,GAAkB,IAAI,CAAC;IACrC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAChD,IAAI,CAAC;YACH,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACjC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,IAAI,gBAAgB,CACxB,iCAAiC,OAAO,EAAE,EAC1C,OAAO,EACP,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAC9B,CAAC;QACJ,CAAC;QACD,UAAU,GAAG,OAAO,CAAC;IACvB,CAAC;IAED,wEAAwE;IACxE,MAAM,aAAa,GAAG,wBAAwB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,aAAa,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;IAEnD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,gBAAgB,CACxB,yBAAyB,GAAG,CAAC,MAAM,CAAC,MAAM,WAAW,EACrD,UAAU,EACV,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACrB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ;gBAClC,OAAO,EAAE,CAAC,CAAC,OAAO;aACnB,CAAC,CAAC,CACJ,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/create-kozou.d.ts

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

package/dist/create-kozou.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-kozou.d.ts","sourceRoot":"","sources":["../src/create-kozou.ts"],"names":[],"mappings":""}

package/dist/create-kozou.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// `create-kozou` bin entry. Thin wrapper around createKozouScaffold().
+import { createKozouScaffold, KozouScaffoldError } from './scaffold.js';
+async function main() {
+    const target = process.argv[2];
+    if (!target || target === '--help' || target === '-h') {
+        process.stderr.write('Usage: create-kozou <directory>\n');
+        process.exit(target ? 0 : 1);
+    }
+    try {
+        await createKozouScaffold({ target });
+    }
+    catch (err) {
+        if (err instanceof KozouScaffoldError) {
+            process.stderr.write(`${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    process.stderr.write(`Scaffolded ${target}/\n`);
+    process.stderr.write(`Next: cd ${target} && cp .env.example .env && docker compose up\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`create-kozou: fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=create-kozou.js.map

package/dist/create-kozou.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-kozou.js","sourceRoot":"","sources":["../src/create-kozou.ts"],"names":[],"mappings":";AACA,uEAAuE;AAEvE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExE,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,CAAC;QACH,MAAM,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;YACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;YACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,MAAM,KAAK,CAAC,CAAC;IAChD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,YAAY,MAAM,iDAAiD,CACpE,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export declare const PACKAGE_VERSION: string;
+export { loadConfig, KozouConfigError } from './config.js';
+export type { KozouConfig, KozouConfigIssue, LoadConfigOptions } from './config.js';
+export { inspectCommand } from './commands/inspect.js';
+export type { InspectOptions } from './commands/inspect.js';
+export { mcpCommand } from './commands/mcp.js';
+export type { McpOptions } from './commands/mcp.js';
+export { devCommand } from './commands/dev.js';
+export type { DevOptions } from './commands/dev.js';
+export { createKozouScaffold, KozouScaffoldError } from './scaffold.js';
+export type { CreateScaffoldOptions } from './scaffold.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,eAAe,QAAc,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEpF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxE,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+// kozou (CLI package): public API surface for adopters embedding the
+// commands programmatically. The bin entry points live in cli.ts and
+// create-kozou.ts; this module re-exports the underlying primitives so
+// integrators can build their own glue if they need to.
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+// `package.json` is the single source of truth for the version. Read it
+// at module load (the same createRequire idiom commands/dev-runtime.ts
+// uses to resolve a sibling package) instead of hardcoding a copy here,
+// so a release bump in package.json can never drift from this constant.
+// `../package.json` resolves to packages/kozou/package.json from the
+// compiled dist/index.js, and npm always ships package.json in the
+// published tarball.
+const require = createRequire(import.meta.url);
+const pkg = JSON.parse(readFileSync(require.resolve('../package.json'), 'utf8'));
+export const PACKAGE_VERSION = pkg.version;
+export { loadConfig, KozouConfigError } from './config.js';
+export { inspectCommand } from './commands/inspect.js';
+export { mcpCommand } from './commands/mcp.js';
+export { devCommand } from './commands/dev.js';
+export { createKozouScaffold, KozouScaffoldError } from './scaffold.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,qEAAqE;AACrE,uEAAuE;AACvE,wDAAwD;AAExD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,wEAAwE;AACxE,uEAAuE;AACvE,wEAAwE;AACxE,wEAAwE;AACxE,qEAAqE;AACrE,mEAAmE;AACnE,qBAAqB;AACrB,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAE9E,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC,OAAO,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/scaffold.d.ts

@@ -0,0 +1,11 @@
+export type CreateScaffoldOptions = {
+    /** Target directory. Must not already exist. */
+    target: string;
+    /** Override the templates directory (used by unit tests). */
+    templatesDir?: string;
+};
+export declare class KozouScaffoldError extends Error {
+    constructor(message: string);
+}
+export declare function createKozouScaffold(opts: CreateScaffoldOptions): Promise<void>;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,qBAAqB,GAAG;IAClC,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAyBD,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBpF"}

package/dist/scaffold.js

@@ -0,0 +1,65 @@
+// `create-kozou` scaffolding logic.
+//
+// Copies the contents of packages/kozou/src/templates/ into the target
+// directory the user picks. Renames env.example to .env.example along
+// the way so the scaffolded project ships a real dotfile (the template
+// stays a normal file because npm's tarball handling for dotfiles
+// inside published packages can be surprising).
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const DEFAULT_TEMPLATE_DIR = fileURLToPath(new URL('./templates', import.meta.url));
+export class KozouScaffoldError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KozouScaffoldError';
+    }
+}
+async function copyRecursive(src, dest) {
+    const entries = await readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = join(src, entry.name);
+        let targetName = entry.name;
+        // env.example -> .env.example so the scaffolded project has a real
+        // dotfile but the template itself stays out of dotfile-tooling
+        // edge cases when published to npm.
+        if (entry.isFile() && entry.name === 'env.example') {
+            targetName = '.env.example';
+        }
+        const destPath = join(dest, targetName);
+        if (entry.isDirectory()) {
+            await mkdir(destPath, { recursive: true });
+            await copyRecursive(sourcePath, destPath);
+        }
+        else if (entry.isFile()) {
+            const content = await readFile(sourcePath, 'utf8');
+            await writeFile(destPath, content, 'utf8');
+        }
+        // Symlinks and other entry kinds are skipped intentionally.
+    }
+}
+export async function createKozouScaffold(opts) {
+    const target = (opts.target ?? '').trim();
+    if (target === '') {
+        throw new KozouScaffoldError('create-kozou: target directory is required');
+    }
+    const templatesDir = opts.templatesDir ?? DEFAULT_TEMPLATE_DIR;
+    // Create any missing parent directories, then create the target itself
+    // with a NON-recursive mkdir so an already-existing target fails
+    // atomically with EEXIST. A recursive mkdir silently succeeds on an
+    // existing directory, so the previous existsSync()-then-mkdir guard had
+    // a TOCTOU window (the target could be created between the check and the
+    // mkdir); letting mkdir own the "must not exist" check closes it.
+    await mkdir(dirname(target), { recursive: true });
+    try {
+        await mkdir(target);
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            throw new KozouScaffoldError(`create-kozou: "${target}" already exists`);
+        }
+        throw err;
+    }
+    await copyRecursive(templatesDir, target);
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

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

package/dist/templates/docker-compose.yml

@@ -0,0 +1,64 @@
+# Docker Compose stack for a kozou project.
+#
+# Brings up:
+#   - postgres   PostgreSQL 16 (the source of truth)
+#   - postgrest  REST adapter consumed by the Kozou DataAdapter
+#                (MIT-licensed external dependency, not bundled)
+#   - kozou      `kozou dev` - the bundled Admin UI + MCP HTTP server
+#                (ghcr.io/kozou-dev/kozou). Binds 0.0.0.0 inside the
+#                container so the port mappings below reach your host.
+#
+# Customize the credentials in .env before running `docker compose up`.
+
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-kozou}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-kozou}
+      POSTGRES_DB: ${POSTGRES_DB:-kozou}
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - ./migrations:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-kozou}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  postgrest:
+    image: postgrest/postgrest:latest
+    environment:
+      PGRST_DB_URI: postgres://${POSTGRES_USER:-kozou}:${POSTGRES_PASSWORD:-kozou}@postgres:5432/${POSTGRES_DB:-kozou}
+      PGRST_DB_SCHEMA: public
+      PGRST_DB_ANON_ROLE: ${POSTGRES_USER:-kozou}
+    ports:
+      - "3000:3000"
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  kozou:
+    # `kozou dev` spawns the bundled @kozou/svelte-ui Admin UI and the
+    # MCP HTTP server (Kozou v0.1 spec §9.1). Both bind 0.0.0.0 inside
+    # the container so the port mappings below reach your host.
+    image: ghcr.io/kozou-dev/kozou:v0.1.1
+    command: ["dev"]
+    environment:
+      DATABASE_URL: postgres://${POSTGRES_USER:-kozou}:${POSTGRES_PASSWORD:-kozou}@postgres:5432/${POSTGRES_DB:-kozou}
+      KOZOU_ADAPTER_URL: http://postgrest:3000
+      # The Admin UI is a SvelteKit (adapter-node) app. Without ORIGIN
+      # it assumes https and rejects every form POST (create / edit /
+      # delete) over plain http with a 403 "Cross-site POST forbidden".
+      # Set it to the exact URL you open in the browser; override if you
+      # publish the Admin UI on a different host or port.
+      ORIGIN: ${KOZOU_ORIGIN:-http://localhost:3333}
+    depends_on:
+      postgres:
+        condition: service_healthy
+      postgrest:
+        condition: service_started
+    ports:
+      - "3333:3333"   # Admin UI
+      - "3334:3334"   # MCP HTTP

package/dist/templates/env.example

@@ -0,0 +1,17 @@
+# Copy this file to .env and fill in the real values before running
+# `docker compose up`.
+
+POSTGRES_USER=kozou
+POSTGRES_PASSWORD=change-me
+POSTGRES_DB=kozou
+POSTGRES_PORT=5432
+
+# Used by kozou + postgrest at runtime; defaults match the compose stack.
+DATABASE_URL=postgres://kozou:change-me@postgres:5432/kozou
+KOZOU_ADAPTER_URL=http://postgrest:3000
+
+# Public URL you open the Admin UI on (v0.1.1). The bundled SvelteKit
+# (adapter-node) server needs this to accept form submissions over plain
+# http — without it, create / edit / delete are rejected with a 403
+# "Cross-site POST forbidden". Override if you serve the UI elsewhere.
+KOZOU_ORIGIN=http://localhost:3333

package/dist/templates/kozou.config.yaml

@@ -0,0 +1,29 @@
+# kozou.config.yaml
+#
+# Every field has a sensible default; only set what you need to override.
+# All ${VAR} and ${VAR:-fallback} placeholders are expanded against the
+# process environment at startup.
+
+database:
+  url: ${DATABASE_URL}
+  schemas: [public]
+
+server:
+  ui:
+    port: 3333
+    host: 0.0.0.0
+  mcp:
+    http:
+      port: 3334
+      host: 0.0.0.0
+    stdio: false
+
+adapter:
+  type: postgrest
+  url: ${KOZOU_ADAPTER_URL:-http://postgrest:3000}
+
+uiHints:
+  path: ./ui-hints.yaml
+
+cache:
+  ttlMs: 60000