@usestatemachines/cli 0.0.0-stage → 0.1.0

package/dist/doctor.js

@@ -0,0 +1,239 @@
+import { join } from 'node:path';
+import { skill } from './agents/bundled.js';
+import { agentDestinations } from './agents/destinations.js';
+import { withinDeadline } from './api-internal.js';
+import { apiOriginFromEnvironment, productionOrigin, profileNameFromEnvironment, } from './context-types.js';
+import { CliError, unconfirmedRevocations } from './errors.js';
+import { commandError } from './output.js';
+import { findProjectRoot } from './project-roots.js';
+import { checkLatest } from './update.js';
+const ok = (message) => ({ status: 'ok', message, fix: null });
+const skip = (message) => ({
+    status: 'skipped',
+    message,
+    fix: null,
+});
+const warning = (message, fix) => ({
+    status: 'warning',
+    message,
+    fix,
+});
+export async function runDoctor(context, input) {
+    const { io } = context;
+    const checks = [];
+    async function check(name, action) {
+        const options = { signal: io.signal, deadline: io.now() + 5000 };
+        try {
+            const result = await withinDeadline(io, options, (signal) => action({ ...options, signal }));
+            checks.push({ name, ...result });
+        }
+        catch (error) {
+            if (io.signal.aborted) {
+                throw new CliError('cli.cancelled');
+            }
+            const failure = await commandError(error, io.signal);
+            checks.push({
+                name,
+                status: 'failed',
+                message: failure.message,
+                fix: failure.document.error.next[0]?.command ??
+                    'Run statemachines doctor again.',
+            });
+        }
+    }
+    const environment = io.host.environment;
+    async function selected(options) {
+        const state = await context.accounts.inspect(options);
+        const name = context.globals.profile ??
+            profileNameFromEnvironment(environment.STATEMACHINES_PROFILE) ??
+            state.defaultProfile;
+        return state.profiles.find((profile) => profile.name === name) ?? null;
+    }
+    async function origin(options) {
+        const configured = apiOriginFromEnvironment(environment.STATEMACHINES_BASE_URL);
+        if (configured !== null) {
+            return configured;
+        }
+        return environment.STATEMACHINES_API_KEY === undefined
+            ? ((await selected(options))?.origin ?? productionOrigin)
+            : productionOrigin;
+    }
+    await check('Node', async () => {
+        const [major = 0, minor = 0] = io.host.nodeVersion
+            .replace(/^v/, '')
+            .split('.')
+            .map(Number);
+        return major > 20 || (major === 20 && minor >= 20)
+            ? ok(`Node ${io.host.nodeVersion}`)
+            : {
+                status: 'failed',
+                message: `Node ${io.host.nodeVersion} is unsupported.`,
+                fix: 'Install Node 20.20 or later.',
+            };
+    });
+    await check('Credential', async (options) => {
+        if (environment.STATEMACHINES_API_KEY !== undefined) {
+            return ok(`Workspace key from STATEMACHINES_API_KEY at ${await origin(options)}.`);
+        }
+        const profile = await selected(options);
+        if (profile === null) {
+            throw new CliError('cli.no_credential');
+        }
+        const expected = await origin(options);
+        if (expected !== profile.origin) {
+            throw new CliError('cli.origin_mismatch');
+        }
+        const expires = Date.parse(profile.expiresAt);
+        if (expires <= io.now()) {
+            throw new CliError('cli.credential_expired');
+        }
+        if (expires - io.now() <= 14 * 24 * 60 * 60 * 1000) {
+            return warning(`Profile ${profile.name} expires within 14 days.`, 'Run statemachines login.');
+        }
+        return ok(`Profile ${profile.name} at ${profile.origin}; expires ${new Date(expires).toISOString()}.`);
+    });
+    await check('API credential', async (options) => {
+        if (input.offline) {
+            return skip('Offline mode.');
+        }
+        const account = await context.resolveAccount(options);
+        const me = await account.sdk.me();
+        const absoluteExpiry = 'expiresAt' in me.credential && me.credential.expiresAt instanceof Date
+            ? me.credential.expiresAt.getTime()
+            : null;
+        const idleExpiry = me.credential.kind === 'cli_token' &&
+            'idleExpiresAt' in me.credential &&
+            me.credential.idleExpiresAt instanceof Date
+            ? me.credential.idleExpiresAt.getTime()
+            : null;
+        const expires = absoluteExpiry === null
+            ? idleExpiry
+            : idleExpiry === null
+                ? absoluteExpiry
+                : Math.min(absoluteExpiry, idleExpiry);
+        return expires !== null && expires - io.now() <= 14 * 24 * 60 * 60 * 1000
+            ? warning('The credential works and expires within 14 days.', 'Replace the credential before it expires.')
+            : ok('The credential works.');
+    });
+    await check('Workspace', async (options) => {
+        if (input.offline) {
+            return skip('Offline mode. Workspace access was not checked.');
+        }
+        const account = await context.resolveAccount(options);
+        const workspace = await account.resolveWorkspace(options);
+        return workspace === null
+            ? warning('No workspace selected.', 'Run statemachines link --workspace <id>.')
+            : ok(`${workspace.name} from ${workspace.source}.`);
+    });
+    await check('Credential store', async (options) => {
+        if (environment.STATEMACHINES_API_KEY !== undefined) {
+            return ok('The credential comes from the environment.');
+        }
+        const profile = await selected(options);
+        if (profile === null) {
+            throw new CliError('cli.no_credential');
+        }
+        if (profile.store === 'file') {
+            for (const name of ['config.json', 'credentials.json']) {
+                const inspection = await io.files.inspect(join(io.host.configHome, name), options);
+                if (inspection.kind !== 'file') {
+                    throw new CliError('cli.credentials_invalid');
+                }
+                if (io.host.platform !== 'win32' && (inspection.mode & 0o077) !== 0) {
+                    return warning(`${name} is readable by other users.`, 'Restrict the file permissions to your user.');
+                }
+            }
+            return ok(io.host.platform === 'win32'
+                ? 'Protected file in the user application data directory.'
+                : 'Protected files are accessible only to your user.');
+        }
+        const result = await io.nativeKeychain.executeInChild({ kind: 'probe' }, options);
+        if (result.kind === 'timed-out') {
+            throw new CliError('cli.keychain_timeout');
+        }
+        if (result.kind === 'module-unavailable') {
+            throw new CliError('cli.keychain_unavailable');
+        }
+        if (result.kind !== 'available') {
+            throw new CliError('cli.keychain_denied');
+        }
+        return ok('The keychain is available.');
+    });
+    await check('Pending account changes', async (options) => {
+        if (input.offline) {
+            const state = await context.accounts.inspect(options);
+            return state.pendingAcknowledgements +
+                state.pendingRevocations +
+                state.pendingCleanup ===
+                0
+                ? ok('No pending account changes.')
+                : warning(`Pending account changes: ${state.pendingAcknowledgements + state.pendingRevocations + state.pendingCleanup}. Credential cleanup: ${state.pendingCleanup}.`, state.pendingCleanup > 0
+                    ? 'Check credential-store access and run statemachines doctor again.'
+                    : state.pendingRevocations > 0
+                        ? 'Restore credential access and rerun doctor, or revoke the sessions in dashboard settings.'
+                        : 'Run statemachines doctor with a network connection.');
+        }
+        const report = await context.accounts.reconcile('doctor', options);
+        const state = await context.accounts.inspect(options);
+        const unconfirmed = report.unconfirmed.length;
+        if (report.pending.length + state.pendingCleanup === 0) {
+            if (unconfirmed === 0) {
+                return ok('No pending account changes.');
+            }
+            const { problem, remedy } = unconfirmedRevocations(unconfirmed);
+            return warning(`No pending account changes. ${problem}`, remedy);
+        }
+        return warning(`Pending account changes: ${report.pending.length + state.pendingCleanup}. Credential cleanup: ${state.pendingCleanup}.`, state.pendingCleanup > 0
+            ? 'Check credential-store access and run statemachines doctor again.'
+            : state.pendingRevocations > 0
+                ? 'Restore credential access and rerun doctor, or revoke the sessions in dashboard settings.'
+                : 'Run statemachines doctor again with a network connection.');
+    });
+    await check('API readiness', async (options) => {
+        if (input.offline) {
+            return skip('Offline mode.');
+        }
+        const ready = await context
+            .anonymousApi(await origin(options))
+            .readiness(options);
+        return ready.ready
+            ? ok('The API is ready.')
+            : {
+                status: 'failed',
+                message: 'The API is reachable but not ready.',
+                fix: 'Try again later.',
+            };
+    });
+    await check('Repository skills', async (options) => {
+        const root = await findProjectRoot(io, options);
+        if (root === null) {
+            return skip('This directory is not in a repository.');
+        }
+        let found = false;
+        for (const agent of agentDestinations) {
+            const content = await io.files.read(join(root, agent.path), options);
+            if (content === null) {
+                continue;
+            }
+            found = true;
+            if (content.trim() !== skill.trim()) {
+                return warning('The installed State Machines skill differs from the bundled version.', `Run statemachines init --force --agent ${agent.id}.`);
+            }
+        }
+        return found
+            ? ok('Installed State Machines skills match the bundled version.')
+            : skip('No State Machines skill is installed in this repository.');
+    });
+    await check('CLI version', async (options) => {
+        if (input.offline) {
+            return skip('Offline mode.');
+        }
+        const latest = await checkLatest({ io, version: context.version, options });
+        return latest.latest === null
+            ? skip('The latest-version check is cached without a result.')
+            : latest.newer
+                ? warning(`Version ${latest.latest} is available.`, latest.command)
+                : ok(`Version ${context.version} is current.`);
+    });
+    return { checks };
+}

package/dist/env-file.d.ts

@@ -0,0 +1,10 @@
+import { type ApiOrigin } from './context-types.js';
+import type { Io } from './io-types.js';
+import type { EnvironmentFiles } from './program-types.js';
+type Credential = {
+    readonly key: string;
+    readonly origin: ApiOrigin;
+};
+export declare function mergeEnvironment(content: string, credential: Credential): string;
+export declare function createEnvironmentFiles(io: Io): EnvironmentFiles;
+export {};

package/dist/env-file.js

@@ -0,0 +1,254 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { productionOrigin } from './context-types.js';
+import { CliError } from './errors.js';
+const managedNames = new Set([
+    'STATEMACHINES_API_KEY',
+    'STATEMACHINES_BASE_URL',
+]);
+function lineEnd(content, from) {
+    const newline = content.indexOf('\n', from);
+    return newline === -1 ? content.length : newline + 1;
+}
+function skip(content, from, characters) {
+    let index = from;
+    while (index < content.length && characters.includes(content[index] ?? '')) {
+        index += 1;
+    }
+    return index;
+}
+function span(content, offset) {
+    let start = skip(content, offset, ' \t\r');
+    for (;;) {
+        const line = lineEnd(content, start);
+        const equals = content.indexOf('=', start) - start;
+        if (content[start] === '#' || equals < 0 || start + equals >= line) {
+            return { start, end: line, name: null };
+        }
+        const name = content
+            .slice(start, start + equals)
+            .trim()
+            .replace(/^export /, '')
+            .trim();
+        if (name === '') {
+            start += equals + 1;
+            continue;
+        }
+        let value = skip(content, start + equals + 1, '\r');
+        if (content[value] === '\n') {
+            return { start, end: value + 1, name };
+        }
+        value = skip(content, value, ' \t\r\n');
+        const quote = content[value];
+        const closing = quote === '"' || quote === "'" || quote === '`'
+            ? content.indexOf(quote, value + 1)
+            : -1;
+        return {
+            start,
+            end: lineEnd(content, closing === -1 ? value : closing + 1),
+            name,
+        };
+    }
+}
+function managedValue(raw) {
+    const match = /^[^=]*=[ \t]*(?:'([^']*)'|"([^"]*)"|`([^`]*)`|([^\s'"`#][^#\r\n]*?|))[ \t]*(?:#[^\r\n]*)?\r?\n?$/.exec(raw);
+    const unquoted = match?.[4];
+    if (match === null || unquoted?.endsWith('\\')) {
+        throw new CliError('cli.env_invalid');
+    }
+    return (match[2]?.replace(/\\n/g, '\n').replace(/\\r/g, '\r') ??
+        match[1] ??
+        match[3] ??
+        unquoted ??
+        '');
+}
+function assignments(content) {
+    if (/\r(?!\n)[ \t]*(?:export[ \t]+)?STATEMACHINES_(?:API_KEY|BASE_URL)[ \t]*=/.test(content)) {
+        throw new CliError('cli.env_invalid');
+    }
+    const result = [];
+    let offset = 0;
+    while (offset < content.length) {
+        const { start, end, name } = span(content, offset);
+        result.push({
+            raw: content.slice(offset, end),
+            name,
+            value: name !== null && managedNames.has(name)
+                ? managedValue(content.slice(start, end))
+                : null,
+        });
+        offset = end;
+    }
+    return result;
+}
+function managed(parts) {
+    return parts.filter((part) => part.name !== null && managedNames.has(part.name));
+}
+function digest(parts) {
+    return createHash('sha256')
+        .update(JSON.stringify(managed(parts).map((part) => part.raw)))
+        .digest('hex');
+}
+function values(credential) {
+    const entries = new Map([['STATEMACHINES_API_KEY', credential.key]]);
+    if (credential.origin !== productionOrigin) {
+        entries.set('STATEMACHINES_BASE_URL', credential.origin);
+    }
+    for (const value of entries.values()) {
+        if (value.length === 0 || /[\p{Cc}\s#'"`\\]/u.test(value)) {
+            throw new CliError('cli.env_invalid');
+        }
+    }
+    return entries;
+}
+function matches(parts, credential) {
+    const expected = values(credential);
+    const actual = managed(parts);
+    return (actual.length === expected.size &&
+        actual.every((part) => {
+            if (part.name === null ||
+                !expected.has(part.name) ||
+                expected.get(part.name) !== part.value) {
+                return false;
+            }
+            expected.delete(part.name);
+            return true;
+        }));
+}
+export function mergeEnvironment(content, credential) {
+    const parts = assignments(content);
+    const entries = values(credential);
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    const kept = parts
+        .filter((part) => part.name === null || !managedNames.has(part.name))
+        .map((part) => part.raw)
+        .join('');
+    const bom = kept.startsWith('\ufeff') ? '\ufeff' : '';
+    return (bom +
+        [...entries].map(([name, value]) => `${name}=${value}${newline}`).join('') +
+        kept.slice(bom.length));
+}
+export function createEnvironmentFiles(io) {
+    const paths = io.host.platform === 'win32' ? path.win32 : path.posix;
+    const relative = (root, destination) => paths.relative(root, destination).split(paths.sep).join('/');
+    const status = (root, destination, options) => io.git.fileStatus({ repositoryRoot: root, path: relative(root, destination) }, options);
+    const readText = async (file, options) => {
+        try {
+            return (await io.files.read(file, options)) ?? '';
+        }
+        catch (error) {
+            if (error instanceof CliError && error.code === 'cli.file_not_utf8') {
+                throw new CliError('cli.env_invalid', { message: error.message });
+            }
+            throw error;
+        }
+    };
+    const validate = async (root, destination, options) => {
+        const within = paths.relative(root, destination);
+        const top = within.split(paths.sep)[0]?.toLowerCase();
+        if (!paths.isAbsolute(root) ||
+            !paths.isAbsolute(destination) ||
+            /[\r\n\0]/.test(destination) ||
+            within === '' ||
+            top === '.git' ||
+            top === '.statemachines' ||
+            within === '..' ||
+            within.startsWith(`..${paths.sep}`) ||
+            paths.isAbsolute(within)) {
+            throw new CliError('cli.env_path_refused');
+        }
+        let current = destination;
+        let leaf = true;
+        for (;;) {
+            const entry = await io.files.inspect(current, options);
+            if (entry.kind !== 'missing' &&
+                entry.kind !== (leaf ? 'file' : 'directory')) {
+                throw new CliError('cli.env_path_refused');
+            }
+            const parent = paths.dirname(current);
+            if (parent === current) {
+                break;
+            }
+            current = parent;
+            leaf = false;
+        }
+        if ((await status(root, destination, options)).tracked) {
+            throw new CliError('cli.env_path_refused');
+        }
+    };
+    const ignore = async (root, destination, options) => {
+        if ((await status(root, destination, options)).ignored) {
+            return;
+        }
+        for (const directory of new Set([root, paths.dirname(destination)])) {
+            const ignoreFile = paths.join(directory, '.gitignore');
+            const current = await readText(ignoreFile, options);
+            const newline = current.includes('\r\n') ? '\r\n' : '\n';
+            const rule = `/${relative(directory, destination).replace(/[\\*?[\]#! ]/g, '\\$&')}`;
+            const prefix = current.length > 0 && !current.endsWith('\n')
+                ? `${current}${newline}`
+                : current;
+            await io.files.atomicWrite(ignoreFile, `${prefix}${rule}${newline}`, 'public', options);
+            if ((await status(root, destination, options)).ignored) {
+                return;
+            }
+        }
+        throw new CliError('cli.git');
+    };
+    const locked = (root, options, action) => io.files.withLock(paths.join(root, '.statemachines', '.lock'), options, action);
+    const read = async (target, options) => {
+        await validate(target.repositoryRoot, target.path, options);
+        if (!(await status(target.repositoryRoot, target.path, options)).ignored) {
+            throw new CliError('cli.env_path_refused');
+        }
+        return readText(target.path, options);
+    };
+    return {
+        async prepare(file, options) {
+            if (/[\r\n\0]/.test(file)) {
+                throw new CliError('cli.env_path_refused');
+            }
+            const repositoryRoot = await io.files.findRepositoryRoot(io.host.cwd, options);
+            if (repositoryRoot === null) {
+                throw new CliError('cli.env_path_refused');
+            }
+            const destination = paths.resolve(io.host.cwd, file);
+            await validate(repositoryRoot, destination, options);
+            return locked(repositoryRoot, options, async () => {
+                await validate(repositoryRoot, destination, options);
+                const content = await readText(destination, options);
+                const expectedManagedDigest = digest(assignments(content));
+                await ignore(repositoryRoot, paths.join(repositoryRoot, '.statemachines'), options);
+                await ignore(repositoryRoot, destination, options);
+                return { repositoryRoot, path: destination, expectedManagedDigest };
+            });
+        },
+        async write(target, credential, options, commit) {
+            values(credential);
+            await validate(target.repositoryRoot, target.path, options);
+            await locked(target.repositoryRoot, options, async () => {
+                const content = await read(target, options);
+                const parts = assignments(content);
+                if (matches(parts, credential)) {
+                    await commit();
+                    return;
+                }
+                if (digest(parts) !== target.expectedManagedDigest) {
+                    throw new CliError('cli.env_changed');
+                }
+                await io.files.atomicWrite(target.path, mergeEnvironment(content, credential), 'private-file', options);
+                await commit();
+            });
+        },
+        async commitIfMatches(target, credential, options, commit) {
+            await validate(target.repositoryRoot, target.path, options);
+            return locked(target.repositoryRoot, options, async () => {
+                const matched = matches(assignments(await read(target, options)), credential);
+                if (matched) {
+                    await commit();
+                }
+                return matched;
+            });
+        },
+    };
+}