@sequenceholdings/studio-cli 0.1.22 → 0.1.24

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;

package/dist/app/scaffold.js

@@ -0,0 +1,263 @@
+/**
+ * Scaffold ORM / function / artifact into an app monorepo and keep
+ * sequence.app.yml in sync. Delegates to each primitive's real `init`.
+ */
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { functionsInitCommand } from '../functions/commands.js';
+import { parseArgs } from '../process/commands.js';
+import { currentVersion } from '../update-check.js';
+import { defaultDeployOrder, extendDeployOrder, loadAppManifest, ormNamespaceFromAppId, titleizeSlug, writeAppManifest, } from './manifest.js';
+const LOG = '[seq-studio]';
+const APP_MANIFEST_LABEL = 'sequence.app.yml';
+export function defaultScaffoldNames(_appId) {
+    return { functionName: 'hello' };
+}
+function primitiveIdFor({ kind, name }) {
+    switch (kind) {
+        case 'orm':
+            return `${name}-orm`;
+        case 'artifact':
+            return `${name}-ui`;
+        case 'function':
+            return name;
+    }
+}
+function relativePathFor({ kind, appId, name, }) {
+    switch (kind) {
+        case 'orm':
+            return join('orm', ormNamespaceFromAppId(appId));
+        case 'function':
+            return join('functions', name);
+        case 'artifact':
+            return 'artifact';
+    }
+}
+function buildPrimitiveEntry({ kind, appId, name, dependsOn, }) {
+    const path = relativePathFor({ kind, appId, name }).replace(/\\/g, '/');
+    const id = primitiveIdFor({ kind, name: kind === 'orm' || kind === 'artifact' ? appId : name });
+    const base = { id, kind, path, depends_on: dependsOn };
+    switch (kind) {
+        case 'orm':
+            return { ...base, namespace: ormNamespaceFromAppId(appId) };
+        case 'function':
+            return { ...base, slug: name };
+        case 'artifact':
+            return { ...base, project_id: appId };
+    }
+}
+async function rewriteArtifactIdentity({ artifactDir, appId, }) {
+    const title = titleizeSlug(appId);
+    const manifestPath = join(artifactDir, 'artifact.bundle.yml');
+    if (existsSync(manifestPath)) {
+        const body = await readFile(manifestPath, 'utf8');
+        const next = body
+            .replace(/(project_id:\s*)\S+/g, `$1${appId}`)
+            .replace(/^(\s*)title:\s*.*$/m, `$1title: "${title}"`);
+        if (next !== body)
+            await writeFile(manifestPath, next, 'utf8');
+    }
+    const pkgPath = join(artifactDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+            pkg.name = appId;
+            await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+        }
+        catch {
+            // leave non-JSON package.json alone
+        }
+    }
+}
+async function scaffoldOrm({ absPath }) {
+    const { runOrmCommand } = await import('../orm/delegate.js');
+    const code = await runOrmCommand('init', [absPath]);
+    if (code !== 0) {
+        throw new Error(`orm init failed for ${absPath} (exit ${code}). ` +
+            '`seq-studio init --with orm` requires `@sequenceholdings/orm` ' +
+            '(workspace / internal installs today; not yet available via public npm).');
+    }
+}
+async function scaffoldArtifact({ absPath, appId, }) {
+    const { runCli } = await import('@sequenceholdings/artifact-studio/cli');
+    const code = await runCli(['init', absPath]);
+    if (code !== 0) {
+        throw new Error(`artifact init failed for ${absPath} (exit ${code})`);
+    }
+    await rewriteArtifactIdentity({ artifactDir: absPath, appId });
+}
+async function scaffoldFunction({ absPath }) {
+    const code = await functionsInitCommand(parseArgs([absPath]));
+    if (code !== 0) {
+        throw new Error(`functions init failed for ${absPath} (exit ${code})`);
+    }
+}
+async function scaffoldKind({ kind, appRoot, appId, name, }) {
+    const relPath = relativePathFor({ kind, appId, name }).replace(/\\/g, '/');
+    const absPath = join(appRoot, relPath);
+    const entry = buildPrimitiveEntry({ kind, appId, name, dependsOn: [] });
+    switch (kind) {
+        case 'orm':
+            await mkdir(dirname(absPath), { recursive: true });
+            await scaffoldOrm({ absPath });
+            break;
+        case 'function':
+            await scaffoldFunction({ absPath });
+            break;
+        case 'artifact':
+            await mkdir(absPath, { recursive: true });
+            await scaffoldArtifact({ absPath, appId });
+            break;
+    }
+    return entry;
+}
+function applyDefaultDependsOn(primitives) {
+    const orm = primitives.find((entry) => entry.kind === 'orm');
+    if (!orm)
+        return primitives;
+    return primitives.map((entry) => {
+        if (entry.kind === 'orm' || entry.depends_on.length > 0)
+            return entry;
+        return { ...entry, depends_on: [orm.id] };
+    });
+}
+export async function initAppMonorepo({ rootDir, appId, kinds, names = defaultScaffoldNames(appId), description, }) {
+    if (kinds.length === 0) {
+        throw new Error('select at least one primitive via --with orm,function,artifact (or --orm --function …)');
+    }
+    const appRoot = resolve(rootDir);
+    if (existsSync(join(appRoot, 'sequence.app.yml'))) {
+        throw new Error(`${join(appRoot, 'sequence.app.yml')} already exists — refusing to re-init`);
+    }
+    if (existsSync(appRoot)) {
+        const { readdir } = await import('node:fs/promises');
+        const entries = await readdir(appRoot).catch((error) => {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        });
+        if (entries.length > 0) {
+            throw new Error(`${appRoot} is not empty — init into a new directory, or remove existing files first`);
+        }
+    }
+    await mkdir(appRoot, { recursive: true });
+    try {
+        const version = currentVersion();
+        const primitives = [];
+        for (const kind of kinds) {
+            const name = kind === 'function' ? names.functionName : appId;
+            primitives.push(await scaffoldKind({ kind, appRoot, appId, name }));
+        }
+        const withDeps = applyDefaultDependsOn(primitives);
+        const manifest = {
+            schema_version: 1,
+            app: {
+                id: appId,
+                title: titleizeSlug(appId),
+                ...(description !== undefined ? { description } : {}),
+            },
+            studio: {
+                created_with: version,
+                min_cli: version,
+            },
+            primitives: withDeps,
+            deploy: {
+                order: defaultDeployOrder(withDeps),
+                on_error: 'stop',
+            },
+        };
+        await writeAppManifest({ rootDir: appRoot, manifest });
+        await writeFile(join(appRoot, '.gitignore'), ['node_modules/', 'dist/', '.env', '.env.*', '!.env.example', '.DS_Store', '*.log'].join('\n') + '\n', 'utf8');
+        return manifest;
+    }
+    catch (error) {
+        // Directory was empty (or newly created) — remove partial scaffolds so a
+        // retry can `init` into the same path without a manual cleanup.
+        await rm(appRoot, { recursive: true, force: true }).catch(() => {
+            /* best-effort */
+        });
+        throw error;
+    }
+}
+export async function addPrimitiveToApp({ rootDir, kind, name, }) {
+    const appRoot = resolve(rootDir);
+    const manifest = await loadAppManifest(appRoot);
+    const appId = manifest.app.id;
+    if (kind === 'orm') {
+        throw new Error('adding a second orm namespace is not supported via `seq-studio add` yet — edit sequence.app.yml and scaffold with `seq-studio orm init` manually');
+    }
+    if (kind === 'artifact' && manifest.primitives.some((entry) => entry.kind === 'artifact')) {
+        throw new Error('this app already has an artifact primitive — remove it from sequence.app.yml before re-adding');
+    }
+    const entryId = primitiveIdFor({ kind, name: kind === 'artifact' ? appId : name });
+    if (manifest.primitives.some((entry) => entry.id === entryId)) {
+        throw new Error(`primitive id "${entryId}" already exists in sequence.app.yml`);
+    }
+    const relPath = relativePathFor({ kind, appId, name }).replace(/\\/g, '/');
+    if (manifest.primitives.some((entry) => entry.path === relPath)) {
+        throw new Error(`path "${relPath}" is already declared in sequence.app.yml`);
+    }
+    const absPath = join(appRoot, relPath);
+    // Refuse before scaffolding so a failed init cannot roll back pre-existing files.
+    if (existsSync(absPath)) {
+        throw new Error(`${relPath} already exists on disk — remove it or choose a different name before \`seq-studio add\``);
+    }
+    try {
+        let entry = await scaffoldKind({ kind, appRoot, appId, name });
+        const orm = manifest.primitives.find((item) => item.kind === 'orm');
+        if (orm && entry.depends_on.length === 0) {
+            entry = { ...entry, depends_on: [orm.id] };
+        }
+        const primitives = [...manifest.primitives, entry];
+        const next = {
+            ...manifest,
+            primitives,
+            deploy: {
+                ...manifest.deploy,
+                order: extendDeployOrder({
+                    existingOrder: manifest.deploy.order,
+                    primitives,
+                    newId: entry.id,
+                }),
+                on_error: manifest.deploy.on_error,
+            },
+        };
+        await writeAppManifest({ rootDir: appRoot, manifest: next });
+        return { manifest: next, entry };
+    }
+    catch (error) {
+        // Safe: absPath did not exist before this invocation.
+        await rm(absPath, { recursive: true, force: true }).catch(() => {
+            /* best-effort */
+        });
+        throw error;
+    }
+}
+export function printInitNextSteps({ appRoot, manifest, }) {
+    const rel = relative(process.cwd(), appRoot);
+    const display = !rel || rel.startsWith('..') ? appRoot : rel;
+    console.log(`${LOG} scaffolded app "${manifest.app.id}" in ${display}`);
+    console.log(`${LOG} wrote ${APP_MANIFEST_LABEL} with ${manifest.primitives.length} primitive(s):`);
+    for (const entry of manifest.primitives) {
+        console.log(`${LOG}   - ${entry.kind.padEnd(9)} ${entry.id}  (${entry.path})`);
+    }
+    console.log('');
+    console.log('Next:');
+    console.log(`  cd ${display}`);
+    for (const entry of manifest.primitives) {
+        console.log(`  (cd ${entry.path} && pnpm install)`);
+    }
+    console.log('  seq-studio login');
+    console.log('  seq-studio deploy -e local --yes');
+    console.log('  # or targeted:');
+    const fn = manifest.primitives.find((entry) => entry.kind === 'function');
+    if (fn) {
+        console.log(`  seq-studio functions deploy --dir ${fn.path} -e local --yes`);
+    }
+    if (manifest.primitives.some((entry) => entry.kind === 'artifact')) {
+        console.log('  seq-studio artifact deploy artifact -e local');
+    }
+    console.log('  # add another function later:');
+    console.log('  seq-studio add function list-types');
+}