@sequenceholdings/studio-cli 0.1.21 → 0.1.24

package/dist/app/deploy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Top-level `seq-studio deploy` — fan out from sequence.app.yml in deploy order.
+ *
+ * Child primitives keep their own deploy/apply verbs; this command only
+ * orchestrates them. Injectable runners keep unit tests offline.
+ */
+import { type AppManifest, type PrimitiveEntry, type PrimitiveKind } from './manifest.js';
+/**
+ * Resolve a manifest primitive path under the app root. Rejects absolute paths,
+ * lexical traversal, and symlink escapes (via realpath) before a deployer runs.
+ * Missing targets keep the lexical candidate after a lexical containment check.
+ */
+export declare function resolveContainedPrimitivePath({ rootDir, entryPath, }: {
+    rootDir: string;
+    entryPath: string;
+}): Promise<string>;
+export type DeployPrimitiveArgs = {
+    entry: PrimitiveEntry;
+    /** Absolute path to the primitive directory. */
+    path: string;
+    env: string;
+    yes: boolean;
+};
+export type PrimitiveDeployers = {
+    [K in PrimitiveKind]: (args: DeployPrimitiveArgs) => Promise<number>;
+};
+export type DeployAppOptions = {
+    rootDir: string;
+    env: string;
+    /** Restrict to these primitive ids (manifest order still applies). */
+    only?: readonly string[];
+    yes?: boolean;
+    dryRun?: boolean;
+    deployers?: PrimitiveDeployers;
+};
+export type DeployAppResult = {
+    attempted: string[];
+    succeeded: string[];
+    failed: string[];
+    skipped: string[];
+    exitCode: number;
+};
+/** Resolve ordered primitive entries for deploy, validating order / --only ids. */
+export declare function resolveDeployEntries({ manifest, only, }: {
+    manifest: AppManifest;
+    only?: readonly string[];
+}): PrimitiveEntry[];
+export declare function createDefaultDeployers(): Promise<PrimitiveDeployers>;
+export declare function deployApp(options: DeployAppOptions): Promise<DeployAppResult>;

package/dist/app/deploy.js

@@ -0,0 +1,197 @@
+/**
+ * Top-level `seq-studio deploy` — fan out from sequence.app.yml in deploy order.
+ *
+ * Child primitives keep their own deploy/apply verbs; this command only
+ * orchestrates them. Injectable runners keep unit tests offline.
+ */
+import { realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { defaultDeployOrder, loadAppManifest, } from './manifest.js';
+const LOG = '[seq-studio]';
+const APP_MANIFEST_HINT = 'sequence.app.yml';
+function assertRelativePrimitivePath(entryPath) {
+    const segments = entryPath.split('/');
+    if (entryPath.length === 0 ||
+        entryPath.trim() !== entryPath ||
+        isAbsolute(entryPath) ||
+        entryPath.includes('\\') ||
+        [...entryPath].some((character) => character.charCodeAt(0) < 0x20) ||
+        segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        throw new Error(`${APP_MANIFEST_HINT}: primitive path must be a relative directory within the app root (got ${JSON.stringify(entryPath)})`);
+    }
+}
+function assertPathInsideRoot({ rootDir, candidate, entryPath, }) {
+    const relativePath = relative(rootDir, candidate);
+    if (relativePath === '..' ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath)) {
+        throw new Error(`${APP_MANIFEST_HINT}: primitive path escapes the app root (got ${JSON.stringify(entryPath)})`);
+    }
+}
+/**
+ * Resolve a manifest primitive path under the app root. Rejects absolute paths,
+ * lexical traversal, and symlink escapes (via realpath) before a deployer runs.
+ * Missing targets keep the lexical candidate after a lexical containment check.
+ */
+export async function resolveContainedPrimitivePath({ rootDir, entryPath, }) {
+    assertRelativePrimitivePath(entryPath);
+    const root = resolve(rootDir);
+    let canonicalRoot = root;
+    try {
+        canonicalRoot = await realpath(root);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    // Resolve against the canonical root so macOS /var → /private/var does not
+    // look like an escape when comparing realpath(root) to a lexical candidate.
+    const candidate = resolve(canonicalRoot, entryPath);
+    assertPathInsideRoot({ rootDir: canonicalRoot, candidate, entryPath });
+    try {
+        const canonicalCandidate = await realpath(candidate);
+        assertPathInsideRoot({
+            rootDir: canonicalRoot,
+            candidate: canonicalCandidate,
+            entryPath,
+        });
+        return canonicalCandidate;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        // Target does not exist yet (dry-run / pre-scaffold) — lexical check stands.
+        return candidate;
+    }
+}
+/** Resolve ordered primitive entries for deploy, validating order / --only ids. */
+export function resolveDeployEntries({ manifest, only, }) {
+    const byId = new Map(manifest.primitives.map((entry) => [entry.id, entry]));
+    const order = manifest.deploy.order && manifest.deploy.order.length > 0
+        ? manifest.deploy.order
+        : defaultDeployOrder(manifest.primitives);
+    for (const id of order) {
+        if (!byId.has(id)) {
+            throw new Error(`${APP_MANIFEST_HINT}: deploy.order references unknown primitive id "${id}"`);
+        }
+    }
+    // Include primitives missing from an incomplete explicit order (append by default).
+    const orderedIds = [...order];
+    for (const entry of manifest.primitives) {
+        if (!orderedIds.includes(entry.id))
+            orderedIds.push(entry.id);
+    }
+    if (only && only.length > 0) {
+        const unknown = only.filter((id) => !byId.has(id));
+        if (unknown.length > 0) {
+            throw new Error(`Unknown primitive id(s) in --only: ${unknown.join(', ')}. Known: ${[...byId.keys()].join(', ')}`);
+        }
+        const onlySet = new Set(only);
+        return orderedIds
+            .filter((id) => onlySet.has(id))
+            .map((id) => byId.get(id));
+    }
+    return orderedIds.map((id) => byId.get(id));
+}
+export async function createDefaultDeployers() {
+    const { runOrmCommand } = await import('../orm/delegate.js');
+    const { functionsDeployCommand } = await import('../functions/commands.js');
+    const { runArtifactCommand } = await import('../artifact/delegate.js');
+    return {
+        async orm({ path, env }) {
+            return runOrmCommand('apply', [path, '--env', env]);
+        },
+        async function({ path, env, yes }) {
+            return functionsDeployCommand({
+                positional: [],
+                flags: {
+                    dir: path,
+                    env,
+                    ...(yes ? { yes: true } : {}),
+                },
+            });
+        },
+        async artifact({ path, env }) {
+            return runArtifactCommand('deploy', [path, '--env', env]);
+        },
+    };
+}
+export async function deployApp(options) {
+    const rootDir = resolve(options.rootDir);
+    const manifest = await loadAppManifest(rootDir);
+    const entries = resolveDeployEntries({ manifest, only: options.only });
+    const onError = manifest.deploy.on_error;
+    const deployers = options.deployers ?? (await createDefaultDeployers());
+    // Validate every selected path before any deployer runs (including dry-run).
+    const resolvedPaths = new Map();
+    for (const entry of entries) {
+        resolvedPaths.set(entry.id, await resolveContainedPrimitivePath({ rootDir, entryPath: entry.path }));
+    }
+    console.log(`${LOG} deploying app "${manifest.app.id}" (${entries.length} primitive(s)) → ${options.env}`);
+    for (const entry of entries) {
+        console.log(`${LOG}   - ${entry.kind.padEnd(9)} ${entry.id}  (${entry.path})`);
+    }
+    if (options.dryRun) {
+        console.log(`${LOG} dry-run: no primitives deployed`);
+        return {
+            attempted: [],
+            succeeded: [],
+            failed: [],
+            skipped: entries.map((entry) => entry.id),
+            exitCode: 0,
+        };
+    }
+    const attempted = [];
+    const succeeded = [];
+    const failed = [];
+    const skipped = [];
+    /** Failed or dependency-skipped ids — blocks transitive `depends_on` edges. */
+    const unavailable = new Set();
+    let stop = false;
+    for (const entry of entries) {
+        if (stop) {
+            skipped.push(entry.id);
+            unavailable.add(entry.id);
+            console.log(`${LOG} skip ${entry.id} (stopped after earlier failure)`);
+            continue;
+        }
+        const blockedBy = entry.depends_on.filter((id) => unavailable.has(id));
+        if (blockedBy.length > 0) {
+            skipped.push(entry.id);
+            unavailable.add(entry.id);
+            console.log(`${LOG} skip ${entry.id} (depends on failed/skipped: ${blockedBy.join(', ')})`);
+            continue;
+        }
+        const path = resolvedPaths.get(entry.id);
+        attempted.push(entry.id);
+        console.log(`${LOG} → ${entry.kind} ${entry.id}`);
+        let code;
+        try {
+            code = await deployers[entry.kind]({
+                entry,
+                path,
+                env: options.env,
+                yes: options.yes === true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`${LOG} ${entry.id} threw: ${message}`);
+            code = 1;
+        }
+        if (code === 0) {
+            succeeded.push(entry.id);
+            console.log(`${LOG} ✓ ${entry.id}`);
+        }
+        else {
+            failed.push(entry.id);
+            unavailable.add(entry.id);
+            console.error(`${LOG} ✗ ${entry.id} exited ${code}`);
+            if (onError === 'stop')
+                stop = true;
+        }
+    }
+    const exitCode = failed.length > 0 ? 1 : 0;
+    console.log(`${LOG} deploy finished: ${succeeded.length} ok, ${failed.length} failed, ${skipped.length} skipped`);
+    return { attempted, succeeded, failed, skipped, exitCode };
+}

package/dist/app/kinds.d.ts

@@ -0,0 +1,10 @@
+import { type PrimitiveKind } from './manifest.js';
+/**
+ * Resolve which primitive kinds to scaffold from CLI flags.
+ *
+ * Supports:
+ *   --with orm,function,artifact
+ *   --with=orm,function
+ *   --orm --function --artifact   (boolean aliases)
+ */
+export declare function resolveRequestedKinds(flags: Record<string, string | true>): PrimitiveKind[];

package/dist/app/kinds.js

@@ -0,0 +1,36 @@
+import { isPrimitiveKind, PRIMITIVE_KINDS } from './manifest.js';
+/**
+ * Resolve which primitive kinds to scaffold from CLI flags.
+ *
+ * Supports:
+ *   --with orm,function,artifact
+ *   --with=orm,function
+ *   --orm --function --artifact   (boolean aliases)
+ */
+export function resolveRequestedKinds(flags) {
+    const kinds = new Set();
+    const withFlag = flags.with;
+    if (withFlag === true) {
+        throw new Error('--with requires a comma-separated list (e.g. --with orm,function,artifact)');
+    }
+    if (typeof withFlag === 'string') {
+        for (const part of withFlag.split(',')) {
+            const trimmed = part.trim().toLowerCase();
+            if (!trimmed)
+                continue;
+            if (!isPrimitiveKind(trimmed)) {
+                throw new Error(`unknown primitive kind '${trimmed}' in --with — expected one of: ${PRIMITIVE_KINDS.join(', ')}`);
+            }
+            kinds.add(trimmed);
+        }
+    }
+    for (const kind of PRIMITIVE_KINDS) {
+        if (flags[kind] === true)
+            kinds.add(kind);
+        else if (typeof flags[kind] === 'string') {
+            throw new Error(`--${kind} is a boolean flag (use --with ${kind} or --${kind} with no value)`);
+        }
+    }
+    // Stable order matching deploy defaults.
+    return PRIMITIVE_KINDS.filter((kind) => kinds.has(kind));
+}

package/dist/app/manifest.d.ts

@@ -0,0 +1,94 @@
+/**
+ * App monorepo root manifest (`sequence.app.yml`).
+ *
+ * Declares which platform primitives live in the repo and where. Required for
+ * scaffolding and for the eventual Applications UI. Crawl-only discovery is
+ * intentionally not supported — `seq-studio init` / `add` own this file.
+ *
+ * v0 kinds: orm | function | artifact. Process/agent can return later.
+ */
+import { z } from 'zod';
+export declare const APP_MANIFEST_FILENAME = "sequence.app.yml";
+export declare const PRIMITIVE_KINDS: readonly ["orm", "function", "artifact"];
+export type PrimitiveKind = (typeof PRIMITIVE_KINDS)[number];
+export declare function isPrimitiveKind(value: string): value is PrimitiveKind;
+declare const primitiveEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        function: "function";
+        orm: "orm";
+        artifact: "artifact";
+    }>;
+    path: z.ZodString;
+    depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    namespace: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    project_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const appManifestSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    app: z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    studio: z.ZodObject<{
+        created_with: z.ZodString;
+        min_cli: z.ZodString;
+    }, z.core.$strip>;
+    primitives: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            function: "function";
+            orm: "orm";
+            artifact: "artifact";
+        }>;
+        path: z.ZodString;
+        depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        namespace: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
+        project_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    deploy: z.ZodDefault<z.ZodObject<{
+        order: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        on_error: z.ZodDefault<z.ZodEnum<{
+            continue: "continue";
+            stop: "stop";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AppManifest = z.infer<typeof appManifestSchema>;
+export type PrimitiveEntry = z.infer<typeof primitiveEntrySchema>;
+/**
+ * Fail closed when the installed CLI is older than `studio.min_cli`, so an
+ * older binary cannot load / rewrite a manifest that requires newer semantics.
+ */
+export declare function assertManifestCliVersion({ manifest, cliVersion, }: {
+    manifest: AppManifest;
+    cliVersion?: string;
+}): void;
+export declare function appManifestPath(rootDir: string): string;
+export declare function parseAppManifest(raw: unknown): AppManifest;
+export declare function loadAppManifest(rootDir: string): Promise<AppManifest>;
+export declare function writeAppManifest({ rootDir, manifest, }: {
+    rootDir: string;
+    manifest: AppManifest;
+}): Promise<string>;
+/** Default deploy order: orm → functions → artifact. */
+export declare function defaultDeployOrder(primitives: readonly PrimitiveEntry[]): string[];
+/**
+ * Extend deploy.order when adding a primitive. Preserves any explicit custom
+ * order; only appends the new id (plus any pre-existing primitives that were
+ * missing from an incomplete order). Falls back to the default kind ranking
+ * when no order is set.
+ */
+export declare function extendDeployOrder({ existingOrder, primitives, newId, }: {
+    existingOrder: readonly string[] | undefined;
+    primitives: readonly PrimitiveEntry[];
+    newId: string;
+}): string[];
+export declare function titleizeSlug(slug: string): string;
+export declare function slugifyAppId(value: string): string;
+/** ORM namespaces use snake_case; map kebab app ids. */
+export declare function ormNamespaceFromAppId(appId: string): string;
+export {};

package/dist/app/manifest.js

@@ -0,0 +1,273 @@
+/**
+ * App monorepo root manifest (`sequence.app.yml`).
+ *
+ * Declares which platform primitives live in the repo and where. Required for
+ * scaffolding and for the eventual Applications UI. Crawl-only discovery is
+ * intentionally not supported — `seq-studio init` / `add` own this file.
+ *
+ * v0 kinds: orm | function | artifact. Process/agent can return later.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { dump as yamlDump, load as yamlLoad } from 'js-yaml';
+import { z } from 'zod';
+import { currentVersion, isNewerVersion } from '../update-check.js';
+export const APP_MANIFEST_FILENAME = 'sequence.app.yml';
+export const PRIMITIVE_KINDS = ['orm', 'function', 'artifact'];
+export function isPrimitiveKind(value) {
+    return PRIMITIVE_KINDS.includes(value);
+}
+const appIdSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z][a-z0-9-]*$/, 'app id must be kebab-case (a-z, 0-9, -)');
+const primitiveEntrySchema = z
+    .object({
+    id: z.string().min(1).max(128),
+    kind: z.enum(PRIMITIVE_KINDS),
+    path: z.string().min(1),
+    depends_on: z.array(z.string().min(1)).default([]),
+    namespace: z.string().min(1).optional(),
+    slug: z.string().min(1).optional(),
+    project_id: z.string().min(1).optional(),
+})
+    .superRefine((entry, ctx) => {
+    if (entry.kind === 'orm' && entry.namespace === undefined) {
+        ctx.addIssue({ code: 'custom', message: `orm primitive "${entry.id}" requires namespace`, path: ['namespace'] });
+    }
+    if (entry.kind === 'function' && entry.slug === undefined) {
+        ctx.addIssue({ code: 'custom', message: `function primitive "${entry.id}" requires slug`, path: ['slug'] });
+    }
+    if (entry.kind === 'artifact' && entry.project_id === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `artifact primitive "${entry.id}" requires project_id`,
+            path: ['project_id'],
+        });
+    }
+});
+export const appManifestSchema = z
+    .object({
+    schema_version: z.literal(1),
+    app: z.object({
+        id: appIdSchema,
+        title: z.string().min(1),
+        description: z.string().optional(),
+    }),
+    studio: z.object({
+        created_with: z.string().min(1),
+        min_cli: z.string().min(1),
+    }),
+    primitives: z.array(primitiveEntrySchema),
+    deploy: z
+        .object({
+        order: z.array(z.string().min(1)).optional(),
+        on_error: z.enum(['stop', 'continue']).default('stop'),
+    })
+        .default({ on_error: 'stop' }),
+})
+    .superRefine((manifest, ctx) => {
+    const seenIds = new Set();
+    const seenPaths = new Set();
+    for (const [index, entry] of manifest.primitives.entries()) {
+        if (seenIds.has(entry.id)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `duplicate primitive id "${entry.id}"`,
+                path: ['primitives', index, 'id'],
+            });
+        }
+        seenIds.add(entry.id);
+        if (seenPaths.has(entry.path)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `duplicate primitive path "${entry.path}"`,
+                path: ['primitives', index, 'path'],
+            });
+        }
+        seenPaths.add(entry.path);
+    }
+    for (const [index, entry] of manifest.primitives.entries()) {
+        for (const [depIndex, dep] of entry.depends_on.entries()) {
+            if (!seenIds.has(dep)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `depends_on references unknown primitive id "${dep}"`,
+                    path: ['primitives', index, 'depends_on', depIndex],
+                });
+            }
+        }
+    }
+    const order = manifest.deploy.order;
+    if (order !== undefined) {
+        const seenOrder = new Set();
+        for (const [index, id] of order.entries()) {
+            if (seenOrder.has(id)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `duplicate deploy.order entry "${id}"`,
+                    path: ['deploy', 'order', index],
+                });
+            }
+            seenOrder.add(id);
+        }
+    }
+    // Effective deploy order (explicit + missing ids, or default kind ranking).
+    const effectiveOrder = order && order.length > 0
+        ? (() => {
+            const ordered = [...order];
+            for (const entry of manifest.primitives) {
+                if (!ordered.includes(entry.id))
+                    ordered.push(entry.id);
+            }
+            return ordered;
+        })()
+        : defaultDeployOrderForValidation(manifest.primitives);
+    const position = new Map(effectiveOrder.map((id, index) => [id, index]));
+    for (const entry of manifest.primitives) {
+        const entryPos = position.get(entry.id);
+        if (entryPos === undefined)
+            continue;
+        for (const dep of entry.depends_on) {
+            const depPos = position.get(dep);
+            if (depPos === undefined)
+                continue;
+            if (depPos >= entryPos) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `deploy order places "${entry.id}" before its dependency "${dep}"`,
+                    path: ['deploy', 'order'],
+                });
+            }
+        }
+    }
+});
+/** Local helper so schema refinement does not depend on later exports. */
+function defaultDeployOrderForValidation(primitives) {
+    const rank = (kind) => {
+        switch (kind) {
+            case 'orm':
+                return 0;
+            case 'function':
+                return 1;
+            case 'artifact':
+                return 2;
+        }
+    };
+    return [...primitives]
+        .sort((a, b) => rank(a.kind) - rank(b.kind) || a.id.localeCompare(b.id))
+        .map((entry) => entry.id);
+}
+/**
+ * Fail closed when the installed CLI is older than `studio.min_cli`, so an
+ * older binary cannot load / rewrite a manifest that requires newer semantics.
+ */
+export function assertManifestCliVersion({ manifest, cliVersion = currentVersion(), }) {
+    const required = manifest.studio.min_cli;
+    if (isNewerVersion(required, cliVersion)) {
+        throw new Error(`This app requires seq-studio >= ${required} (sequence.app.yml studio.min_cli), ` +
+            `but this CLI is ${cliVersion}. Upgrade with: pnpm add -g @sequenceholdings/studio-cli@latest`);
+    }
+}
+export function appManifestPath(rootDir) {
+    return join(resolve(rootDir), APP_MANIFEST_FILENAME);
+}
+export function parseAppManifest(raw) {
+    return appManifestSchema.parse(raw);
+}
+export async function loadAppManifest(rootDir) {
+    const path = appManifestPath(rootDir);
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`No ${APP_MANIFEST_FILENAME} in ${resolve(rootDir)}. Run \`seq-studio init\` to scaffold an app, or cd to the app root.`);
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = yamlLoad(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid ${APP_MANIFEST_FILENAME}: ${message}`);
+    }
+    try {
+        const manifest = parseAppManifest(parsed);
+        assertManifestCliVersion({ manifest });
+        return manifest;
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const detail = error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ');
+            throw new Error(`Invalid ${APP_MANIFEST_FILENAME}: ${detail}`);
+        }
+        throw error;
+    }
+}
+export async function writeAppManifest({ rootDir, manifest, }) {
+    const validated = parseAppManifest(manifest);
+    const path = appManifestPath(rootDir);
+    const body = yamlDump(validated, {
+        lineWidth: 100,
+        noRefs: true,
+        sortKeys: false,
+    });
+    await writeFile(path, `# App monorepo manifest — owned by seq-studio init / add. Do not hand-author without the CLI.\n${body}`, 'utf8');
+    return path;
+}
+/** Default deploy order: orm → functions → artifact. */
+export function defaultDeployOrder(primitives) {
+    const rank = (kind) => {
+        switch (kind) {
+            case 'orm':
+                return 0;
+            case 'function':
+                return 1;
+            case 'artifact':
+                return 2;
+        }
+    };
+    return [...primitives]
+        .sort((a, b) => rank(a.kind) - rank(b.kind) || a.id.localeCompare(b.id))
+        .map((entry) => entry.id);
+}
+/**
+ * Extend deploy.order when adding a primitive. Preserves any explicit custom
+ * order; only appends the new id (plus any pre-existing primitives that were
+ * missing from an incomplete order). Falls back to the default kind ranking
+ * when no order is set.
+ */
+export function extendDeployOrder({ existingOrder, primitives, newId, }) {
+    if (existingOrder === undefined || existingOrder.length === 0) {
+        return defaultDeployOrder(primitives);
+    }
+    const knownIds = new Set(primitives.map((entry) => entry.id));
+    const preserved = existingOrder.filter((id) => knownIds.has(id) && id !== newId);
+    const preservedSet = new Set(preserved);
+    const missingExisting = primitives
+        .map((entry) => entry.id)
+        .filter((id) => id !== newId && !preservedSet.has(id));
+    return [...preserved, ...missingExisting, newId];
+}
+export function titleizeSlug(slug) {
+    return slug
+        .split('-')
+        .filter(Boolean)
+        .map((part) => `${part[0]?.toUpperCase() ?? ''}${part.slice(1)}`)
+        .join(' ');
+}
+export function slugifyAppId(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/** ORM namespaces use snake_case; map kebab app ids. */
+export function ormNamespaceFromAppId(appId) {
+    return appId.replace(/-/g, '_');
+}

package/dist/app/scaffold.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Scaffold ORM / function / artifact into an app monorepo and keep
+ * sequence.app.yml in sync. Delegates to each primitive's real `init`.
+ */
+import { type AppManifest, type PrimitiveEntry, type PrimitiveKind } from './manifest.js';
+export interface ScaffoldNames {
+    functionName: string;
+}
+export declare function defaultScaffoldNames(_appId: string): ScaffoldNames;
+export declare function initAppMonorepo({ rootDir, appId, kinds, names, description, }: {
+    rootDir: string;
+    appId: string;
+    kinds: readonly PrimitiveKind[];
+    names?: ScaffoldNames;
+    description?: string;
+}): Promise<AppManifest>;
+export declare function addPrimitiveToApp({ rootDir, kind, name, }: {
+    rootDir: string;
+    kind: PrimitiveKind;
+    name: string;
+}): Promise<{
+    manifest: AppManifest;
+    entry: PrimitiveEntry;
+}>;
+export declare function printInitNextSteps({ appRoot, manifest, }: {
+    appRoot: string;
+    manifest: AppManifest;
+}): void;