@usestatemachines/cli 0.0.0-stage → 0.1.0

package/dist/commands/environments/wait.d.ts

@@ -0,0 +1,39 @@
+import type { z } from 'zod';
+import type { WorkspaceContext } from '../../context-types.js';
+import { resourceText } from '../../resources/read.js';
+import type { waitInputSchema } from './command.js';
+export declare function run(input: z.infer<typeof waitInputSchema>, context: WorkspaceContext): Promise<{
+    id: string;
+    workspaceId: string;
+    name: string | null;
+    labels: Record<string, string>;
+    status: string;
+    reason: string | null;
+    failure: {
+        appName: string;
+        code: string;
+        message: string;
+    } | null;
+    timeLimitMinutes: number;
+    tokenInUrl: boolean;
+    snapshotId: string | null;
+    apps: {
+        appId: string;
+        name: string;
+        version: string;
+        versionId: string;
+        setup: Record<string, z.JSONType>;
+        services: Record<string, z.JSONType>;
+        url: string;
+    }[];
+    createdBy: {
+        id: string | null;
+        name: string | null;
+        type: string;
+    };
+    createdAt: string;
+    startedAt: string | null;
+    deletedAt: string | null;
+    expiresAt: string | null;
+}>;
+export declare const text: typeof resourceText;

package/dist/commands/environments/wait.js

@@ -0,0 +1,21 @@
+import { resourceError } from '../../resources/create.js';
+import { environment, environmentResult, resourceText, } from '../../resources/read.js';
+export async function run(input, context) {
+    await environment(context, input.id);
+    try {
+        return environmentResult(await context.sdk.environments.wait(input.id, {
+            status: input.status,
+            signal: context.io.signal,
+            ...(input.timeout === undefined
+                ? {}
+                : { timeoutMs: Number(input.timeout) * 1000 }),
+        }));
+    }
+    catch (cause) {
+        throw await resourceError(cause, context, {
+            resource: 'environment',
+            id: input.id,
+        });
+    }
+}
+export const text = resourceText;

package/dist/commands/init/command.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+export declare const packageManagerSchema: z.ZodEnum<{
+    bun: "bun";
+    npm: "npm";
+    pnpm: "pnpm";
+    yarn: "yarn";
+}>;
+export declare const initInputSchema: z.ZodObject<{
+    agent: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    force: z.ZodDefault<z.ZodBoolean>;
+    sdk: z.ZodDefault<z.ZodBoolean>;
+    quickstart: z.ZodDefault<z.ZodBoolean>;
+    env: z.ZodDefault<z.ZodBoolean>;
+    packageManager: z.ZodOptional<z.ZodEnum<{
+        bun: "bun";
+        npm: "npm";
+        pnpm: "pnpm";
+        yarn: "yarn";
+    }>>;
+}, z.core.$strict>;
+export declare const initResultSchema: z.ZodObject<{
+    repositoryRoot: z.ZodString;
+    packageRoot: z.ZodNullable<z.ZodString>;
+    workspace: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>;
+    skills: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        agent: z.ZodString;
+        status: z.ZodLiteral<"unsupported">;
+    }, z.core.$strict>, z.ZodObject<{
+        agent: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+        }>;
+        path: z.ZodString;
+        status: z.ZodEnum<{
+            created: "created";
+            preserved: "preserved";
+            replaced: "replaced";
+            unchanged: "unchanged";
+        }>;
+    }, z.core.$strict>]>>;
+    changedFiles: z.ZodArray<z.ZodString>;
+    packageManager: z.ZodNullable<z.ZodEnum<{
+        bun: "bun";
+        npm: "npm";
+        pnpm: "pnpm";
+        yarn: "yarn";
+    }>>;
+    dependencies: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        status: z.ZodEnum<{
+            installed: "installed";
+            unchanged: "unchanged";
+        }>;
+    }, z.core.$strict>>;
+    environment: z.ZodNullable<z.ZodObject<{
+        path: z.ZodString;
+        workspaceId: z.core.$ZodBranded<z.ZodString, "WorkspaceId", "out">;
+        keyId: z.ZodString;
+        expiresAt: z.ZodString;
+        pendingRevocation: z.ZodBoolean;
+    }, z.core.$strict>>;
+    nextCommand: z.ZodString;
+    installCliCommand: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const initCommand: import("../../command.js").RegisteredCommand;

package/dist/commands/init/command.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { agentDestinations } from '../../agents/destinations.js';
+import { defineCommand } from '../../command.js';
+import { envPullResultSchema } from '../../program-types.js';
+export const packageManagerSchema = z.enum(['npm', 'pnpm', 'yarn', 'bun']);
+export const initInputSchema = z.strictObject({
+    agent: z.array(z.string().min(1)).default([]),
+    force: z.boolean().default(false),
+    sdk: z.boolean().default(false),
+    quickstart: z.boolean().default(false),
+    env: z.boolean().default(false),
+    packageManager: packageManagerSchema.optional(),
+});
+export const initResultSchema = z.strictObject({
+    repositoryRoot: z.string(),
+    packageRoot: z.string().nullable(),
+    workspace: z.strictObject({ id: z.string(), name: z.string() }),
+    skills: z.array(z.union([
+        z.strictObject({ agent: z.string(), status: z.literal('unsupported') }),
+        z.strictObject({
+            agent: z.enum(agentDestinations.map((agent) => agent.id)),
+            path: z.string(),
+            status: z.enum(['created', 'replaced', 'unchanged', 'preserved']),
+        }),
+    ])),
+    changedFiles: z.array(z.string()),
+    packageManager: packageManagerSchema.nullable(),
+    dependencies: z.array(z.strictObject({
+        name: z.string(),
+        status: z.enum(['installed', 'unchanged']),
+    })),
+    environment: envPullResultSchema.nullable(),
+    nextCommand: z.string(),
+    installCliCommand: z.string().nullable(),
+});
+export const initCommand = defineCommand({
+    name: ['init'],
+    summary: 'Link this repository and install the State Machines skill.',
+    need: 'account',
+    workspace: true,
+    destructive: false,
+    streams: false,
+    arguments: [],
+    flags: [
+        {
+            name: 'agent',
+            key: 'agent',
+            type: 'string[]',
+            description: 'Install for claude or codex. Repeat for more agents.',
+        },
+        {
+            name: 'force',
+            key: 'force',
+            type: 'boolean',
+            negatedName: null,
+            description: 'Replace a different existing State Machines skill.',
+        },
+        {
+            name: 'sdk',
+            key: 'sdk',
+            type: 'boolean',
+            negatedName: null,
+            description: 'Add the SDK to the nearest containing package.',
+        },
+        {
+            name: 'quickstart',
+            key: 'quickstart',
+            type: 'boolean',
+            negatedName: null,
+            description: 'Write state-quickstart.mts in the nearest containing package.',
+        },
+        {
+            name: 'env',
+            key: 'env',
+            type: 'boolean',
+            negatedName: null,
+            description: 'Run env pull for .env.local. Replaces its previous key.',
+        },
+        {
+            name: 'package-manager',
+            key: 'packageManager',
+            type: 'string',
+            description: 'Use npm, pnpm, yarn, or bun for --sdk.',
+        },
+    ],
+    input: initInputSchema,
+    result: initResultSchema,
+    progress: z.never(),
+    load: () => import('./run.js'),
+});

package/dist/commands/init/run.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { AccountContext } from '../../context-types.js';
+import type { initInputSchema, initResultSchema } from './command.js';
+type Input = z.infer<typeof initInputSchema>;
+type Result = z.infer<typeof initResultSchema>;
+export declare function run(input: Input, context: AccountContext): Promise<Result>;
+export declare function text(result: Result): string;
+export {};

package/dist/commands/init/run.js

@@ -0,0 +1,422 @@
+import { createHash } from 'node:crypto';
+import { dirname, join, relative } from 'node:path';
+import { z } from 'zod';
+import { quickstart, skill } from '../../agents/bundled.js';
+import { agentDestinations } from '../../agents/destinations.js';
+import { CliError, normalizeError, withErrorDetails } from '../../errors.js';
+import { linkWorkspace } from '../../link.js';
+import { findPackageRoot, findProjectRoot } from '../../project-roots.js';
+import { cliVersion, sdkVersion } from '../../version.js';
+const manifestSchema = z.object({
+    dependencies: z.record(z.string(), z.string()).optional(),
+    devDependencies: z.record(z.string(), z.string()).optional(),
+    optionalDependencies: z.record(z.string(), z.string()).optional(),
+    peerDependencies: z.record(z.string(), z.string()).optional(),
+    packageManager: z.string().optional(),
+    workspaces: z.unknown().optional(),
+});
+const lockfiles = {
+    npm: ['package-lock.json', 'npm-shrinkwrap.json'],
+    pnpm: ['pnpm-lock.yaml'],
+    yarn: ['yarn.lock'],
+    bun: ['bun.lock', 'bun.lockb'],
+};
+function declares(manifest, name) {
+    return [
+        manifest.dependencies,
+        manifest.devDependencies,
+        manifest.optionalDependencies,
+        manifest.peerDependencies,
+    ].some((dependencies) => dependencies?.[name] !== undefined);
+}
+async function readManifest(io, root, options) {
+    try {
+        return manifestSchema.parse(JSON.parse((await io.files.read(join(root, 'package.json'), options)) ?? 'null'));
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            throw error;
+        }
+        throw new CliError('cli.invalid_arguments', {
+            message: 'The package.json file is invalid. Fix it before running init.',
+        });
+    }
+}
+async function checkDestination(io, path, root, options) {
+    let directory = dirname(path);
+    for (;;) {
+        const inspected = await io.files.inspect(directory, options);
+        if (inspected.kind !== 'missing' && inspected.kind !== 'directory') {
+            throw new CliError('cli.config_io');
+        }
+        if (directory === root || dirname(directory) === directory) {
+            break;
+        }
+        directory = dirname(directory);
+    }
+    return io.files.read(path, options);
+}
+async function selectPackageManager(io, root, repository, input, options) {
+    if (input.packageManager !== undefined) {
+        return input.packageManager;
+    }
+    let directory = root;
+    for (;;) {
+        const found = [];
+        for (const manager of [
+            'npm',
+            'pnpm',
+            'yarn',
+            'bun',
+        ]) {
+            for (const name of lockfiles[manager]) {
+                if ((await io.files.inspect(join(directory, name), options)).kind !==
+                    'missing') {
+                    found.push(manager);
+                    break;
+                }
+            }
+        }
+        if (found.length > 0) {
+            const first = found[0];
+            if (found.length === 1 && first !== undefined) {
+                return first;
+            }
+            break;
+        }
+        if (directory === repository || dirname(directory) === directory) {
+            break;
+        }
+        directory = dirname(directory);
+    }
+    throw new CliError('cli.input_required', {
+        message: 'Choose a package manager because no single lockfile identifies one.',
+        next: [
+            {
+                command: 'statemachines init --sdk --package-manager <npm|pnpm|yarn|bun>',
+                reason: 'Choose the package manager for this package.',
+            },
+        ],
+    });
+}
+function installArgs(manager, name, dev) {
+    return manager === 'npm'
+        ? ['install', ...(dev ? ['--save-dev'] : []), name]
+        : ['add', ...(dev ? ['--dev'] : []), name];
+}
+async function workspaceRootArgs(io, manager, manifest, packageRoot, files, options) {
+    if (manager === 'pnpm') {
+        const workspace = await io.files.inspect(join(packageRoot, 'pnpm-workspace.yaml'), options);
+        return workspace.kind === 'file' ? ['--workspace-root'] : [];
+    }
+    if (manager !== 'yarn' || manifest.workspaces === undefined) {
+        return [];
+    }
+    const lock = [...files].find(([path, before]) => before !== null && path.endsWith('yarn.lock'));
+    const berry = /^yarn@(?!1\.)/.test(manifest.packageManager ?? '') ||
+        (lock !== undefined &&
+            (await io.files.read(lock[0], options))?.includes('__metadata:') ===
+                true);
+    return berry ? [] : ['-W'];
+}
+async function digest(io, path, options) {
+    const bytes = await io.files.readBytes(path, options);
+    return bytes === null
+        ? null
+        : createHash('sha256').update(bytes).digest('hex');
+}
+async function dependencyFiles(io, packageRoot, repositoryRoot, options) {
+    const files = new Map();
+    files.set(join(packageRoot, 'package.json'), await digest(io, join(packageRoot, 'package.json'), options));
+    let directory = packageRoot;
+    for (;;) {
+        for (const name of Object.values(lockfiles).flat()) {
+            const path = join(directory, name);
+            files.set(path, await digest(io, path, options));
+        }
+        if (directory === repositoryRoot || dirname(directory) === directory) {
+            return files;
+        }
+        directory = dirname(directory);
+    }
+}
+export async function run(input, context) {
+    const { io } = context;
+    const options = { signal: io.signal, deadline: null };
+    if (input.packageManager !== undefined && !input.sdk) {
+        throw new CliError('cli.invalid_arguments', {
+            message: 'Use --package-manager only with --sdk.',
+        });
+    }
+    const repositoryRoot = await findProjectRoot(io, options);
+    if (repositoryRoot === null) {
+        throw new CliError('cli.invalid_arguments', {
+            message: 'Run init inside a Git repository or a directory with package.json, other than your home directory.',
+        });
+    }
+    const packageRoot = await findPackageRoot(io, io.host.cwd, repositoryRoot, options);
+    if ((input.sdk || input.quickstart) && packageRoot === null) {
+        throw new CliError('cli.invalid_arguments', {
+            message: 'Run this option inside a package with package.json.',
+        });
+    }
+    if (input.env) {
+        if (context.account.kind !== 'cli-token') {
+            throw new CliError('cli.env_requires_login');
+        }
+        if ((await io.files.findRepositoryRoot(io.host.cwd, options)) === null) {
+            throw new CliError('cli.env_path_refused');
+        }
+    }
+    const packageManager = input.sdk && packageRoot !== null
+        ? await selectPackageManager(io, packageRoot, repositoryRoot, input, options)
+        : null;
+    const quickstartPath = input.quickstart && packageRoot !== null
+        ? join(packageRoot, 'state-quickstart.mts')
+        : null;
+    if (quickstartPath !== null) {
+        const existing = await checkDestination(io, quickstartPath, repositoryRoot, options);
+        if (existing !== null && existing !== quickstart) {
+            throw new CliError('cli.invalid_arguments', {
+                message: 'state-quickstart.mts already exists. Rename it before running init --quickstart.',
+            });
+        }
+    }
+    const detected = [];
+    for (const agent of agentDestinations) {
+        if ((await io.files.inspect(join(repositoryRoot, agent.directory), options))
+            .kind === 'directory') {
+            detected.push(agent.id);
+        }
+    }
+    const chosen = input.agent.length > 0 ? [...new Set(input.agent)] : detected;
+    const candidates = context.presentation.mode === 'interactive' && input.agent.length === 0
+        ? agentDestinations
+        : agentDestinations.filter((agent) => chosen.includes(agent.id));
+    for (const agent of candidates) {
+        await checkDestination(io, join(repositoryRoot, agent.path), repositoryRoot, options);
+    }
+    return io.files.withLock(join(repositoryRoot, '.statemachines', 'init.lock'), options, async () => {
+        const manifest = packageRoot === null
+            ? null
+            : await readManifest(io, packageRoot, options);
+        const changedFiles = [];
+        const existing = await context.projects.read();
+        if (existing !== null) {
+            const organizationId = context.account.kind === 'cli-token'
+                ? context.account.organizationId
+                : (await context.sdk.me()).organization?.id;
+            if (organizationId === undefined) {
+                throw new CliError('cli.invalid_response');
+            }
+            if (existing.organizationId !== organizationId) {
+                throw new CliError('cli.organization_mismatch');
+            }
+        }
+        else {
+            const ignorePath = join(repositoryRoot, '.gitignore');
+            const beforeIgnore = await io.files.read(ignorePath, options);
+            const linked = await linkWorkspace(context, { force: false });
+            changedFiles.push(linked.path);
+            if ((await io.files.read(ignorePath, options)) !== beforeIgnore) {
+                changedFiles.push(ignorePath);
+            }
+        }
+        const workspace = await context.resolveWorkspace();
+        if (workspace === null) {
+            throw new CliError('cli.not_linked');
+        }
+        if (existing !== null && workspace.id !== existing.workspaceId) {
+            throw new CliError('cli.workspace_mismatch', {
+                message: 'This repository is linked to another workspace. Use link --force to replace the link.',
+                next: [
+                    {
+                        command: 'statemachines link --force --workspace <id>',
+                        reason: 'Choose the workspace for this repository.',
+                    },
+                ],
+            });
+        }
+        const agents = context.presentation.mode === 'interactive' && input.agent.length === 0
+            ? await io.prompt.multiselect('Choose agents', agentDestinations.map((agent) => ({
+                value: agent.id,
+                label: agent.label,
+            })), detected, options)
+            : chosen;
+        const skills = [];
+        for (const id of agents) {
+            const agent = agentDestinations.find((candidate) => candidate.id === id);
+            if (agent === undefined) {
+                skills.push({ agent: id, status: 'unsupported' });
+                continue;
+            }
+            const path = join(repositoryRoot, agent.path);
+            const before = await io.files.read(path, options);
+            let status;
+            if (before === skill) {
+                status = 'unchanged';
+            }
+            else if (before !== null) {
+                status = input.force ? 'replaced' : 'preserved';
+                if (input.force) {
+                    await io.files.atomicWrite(path, skill, 'public', options);
+                }
+            }
+            else if (await io.files.createIfMissing(path, skill, 'public', options)) {
+                status = 'created';
+            }
+            else {
+                status =
+                    (await io.files.read(path, options)) === skill
+                        ? 'unchanged'
+                        : 'preserved';
+            }
+            if (status === 'created' || status === 'replaced') {
+                changedFiles.push(path);
+            }
+            skills.push({ agent: agent.id, path, status });
+        }
+        if (quickstartPath !== null) {
+            if (await io.files.createIfMissing(quickstartPath, quickstart, 'public', options)) {
+                changedFiles.push(quickstartPath);
+            }
+            else if ((await io.files.read(quickstartPath, options)) !== quickstart) {
+                throw new CliError('cli.invalid_arguments', {
+                    message: 'state-quickstart.mts changed during init. Keep that file and run init without --quickstart.',
+                    details: { changedFiles },
+                });
+            }
+        }
+        const dependencies = [];
+        let installCliCommand = null;
+        if (packageManager !== null &&
+            packageRoot !== null &&
+            manifest !== null) {
+            const cli = '@usestatemachines/cli';
+            const sdk = '@usestatemachines/sdk';
+            const existingCli = declares(manifest, cli);
+            const installCli = !existingCli &&
+                context.presentation.mode === 'interactive' &&
+                (await io.prompt.confirm('Install the CLI as a development dependency?', options));
+            const selected = [
+                { name: sdk, version: sdkVersion, dev: false },
+                ...(existingCli || installCli
+                    ? [{ name: cli, version: cliVersion, dev: true }]
+                    : []),
+            ];
+            const beforeFiles = await dependencyFiles(io, packageRoot, repositoryRoot, options);
+            const rootArgs = await workspaceRootArgs(io, packageManager, manifest, packageRoot, beforeFiles, options);
+            const add = (name, dev) => [
+                ...installArgs(packageManager, name, dev),
+                ...rootArgs,
+            ];
+            if (!existingCli && !installCli) {
+                installCliCommand = [
+                    packageManager,
+                    ...add(`${cli}@${cliVersion}`, true),
+                ].join(' ');
+            }
+            try {
+                for (const dependency of selected) {
+                    if (declares(manifest, dependency.name)) {
+                        dependencies.push({ name: dependency.name, status: 'unchanged' });
+                        continue;
+                    }
+                    const outcome = await io.child.run({
+                        command: packageManager,
+                        args: add(`${dependency.name}@${dependency.version}`, dependency.dev),
+                        cwd: packageRoot,
+                        stdin: 'ignore',
+                        output: 'stderr',
+                        environment: Object.fromEntries(Object.entries(io.host.environment).filter((entry) => entry[1] !== undefined)),
+                        options,
+                    });
+                    if (outcome.kind !== 'exit' || outcome.code !== 0) {
+                        throw new CliError('cli.package_install', {
+                            details: { outcome },
+                        });
+                    }
+                    if (!declares(await readManifest(io, packageRoot, options), dependency.name)) {
+                        throw new CliError('cli.package_install');
+                    }
+                    dependencies.push({ name: dependency.name, status: 'installed' });
+                }
+            }
+            catch (error) {
+                const after = {
+                    signal: new AbortController().signal,
+                    deadline: io.now() + 5_000,
+                };
+                const current = await Promise.all([...beforeFiles].map(async ([path, before]) => (await digest(io, path, after)) === before ? [] : [path]));
+                changedFiles.push(...current.flat());
+                if (options.signal.aborted) {
+                    throw new CliError('cli.cancelled', { details: { changedFiles } });
+                }
+                const failure = normalizeError(error);
+                throw withErrorDetails(failure, {
+                    changedFiles,
+                    cause: failure.document.error.details,
+                });
+            }
+            for (const [path, before] of beforeFiles) {
+                if ((await digest(io, path, options)) !== before) {
+                    changedFiles.push(path);
+                }
+            }
+        }
+        const ignoreFiles = new Map();
+        if (input.env) {
+            for (const directory of new Set([repositoryRoot, io.host.cwd])) {
+                const path = join(directory, '.gitignore');
+                ignoreFiles.set(path, await io.files.read(path, options));
+            }
+        }
+        const environment = input.env
+            ? await context
+                .forWorkspace(workspace)
+                .programs.pullEnvironment('.env.local')
+            : null;
+        if (environment !== null) {
+            changedFiles.push(environment.path);
+            for (const [path, before] of ignoreFiles) {
+                if ((await io.files.read(path, options)) !== before &&
+                    !changedFiles.includes(path)) {
+                    changedFiles.push(path);
+                }
+            }
+        }
+        return {
+            repositoryRoot,
+            packageRoot,
+            workspace: { id: workspace.id, name: workspace.name },
+            skills,
+            changedFiles,
+            packageManager,
+            dependencies,
+            environment,
+            nextCommand: quickstartPath === null
+                ? 'statemachines run -- <command>'
+                : `statemachines run -- npx tsx ${relative(io.host.cwd, quickstartPath).replaceAll('\\', '/')}`,
+            installCliCommand,
+        };
+    });
+}
+export function text(result) {
+    const lines = [`Linked to ${result.workspace.name}.`];
+    for (const installed of result.skills) {
+        lines.push(installed.status === 'unsupported'
+            ? `No skill installed for unsupported agent ${installed.agent}.`
+            : `${installed.agent}: ${installed.status === 'preserved' ? 'kept the existing skill' : installed.status} ${installed.path}.`);
+    }
+    if (result.skills.length === 0) {
+        lines.push('No agents selected. No skill installed.');
+    }
+    lines.push(result.changedFiles.length === 0
+        ? 'No files changed.'
+        : `Changed files:\n${result.changedFiles.map((path) => `  ${path}`).join('\n')}`);
+    if (result.installCliCommand !== null) {
+        lines.push(`Optional CLI dependency: ${result.installCliCommand}`);
+    }
+    lines.push(`Next: ${result.nextCommand}`);
+    return lines.join('\n');
+}

package/dist/commands/link/command.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export declare const linkInputSchema: z.ZodObject<{
+    force: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const linkResultSchema: z.ZodObject<{
+    path: z.ZodString;
+    organizationId: z.ZodString;
+    workspace: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const linkCommand: import("../../command.js").RegisteredCommand;