@storystick/cli 0.0.0-stage → 0.2.0-rc.1

package/dist/setup.js

@@ -0,0 +1,135 @@
+import { existsSync, realpathSync, readFileSync, mkdirSync, writeFileSync, readdirSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { sourceConfiguration, nextSourceConfiguration } from '@storystick/source/recipe';
+import { resolveProjectConnection } from './project-connection.js';
+import { inspectRepository } from './source-git.js';
+/** Inspection is local, read-only and never invokes package scripts. Only names
+ * and identities escape: no environment values, remote credentials or scripts. */
+export function inspectSetup(root) {
+    root = resolve(root);
+    const issues = [];
+    const readJson = (file) => {
+        if (!existsSync(file))
+            return null;
+        try {
+            return JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            issues.push({ path: relative(root, file), message: 'Invalid JSON' });
+            return null;
+        }
+    };
+    const pkg = readJson(resolve(root, 'package.json'));
+    const repository = inspectRepository(root);
+    const configPath = resolve(root, '.storystick/source.json');
+    const raw = readJson(configPath);
+    const config = raw === null ? null : sourceConfiguration.safeParse(raw);
+    if (config && !config.success)
+        issues.push(...config.error.issues.map((issue) => ({
+            path: `.storystick/source.json:${issue.path.join('.')}`,
+            message: issue.message,
+        })));
+    let connection = null;
+    try {
+        const value = resolveProjectConnection(root);
+        if (value)
+            connection = { projectShortId: value.shortId };
+    }
+    catch {
+        issues.push({
+            path: '.env.local',
+            message: 'Incomplete or inconsistent project connection. Run storystick connect for this project.',
+        });
+    }
+    const vercel = readJson(resolve(root, '.vercel/project.json'));
+    const next = [];
+    if (!connection)
+        next.push({
+            reason: 'Connect an existing project, or use init for a new one.',
+            command: 'storystick',
+            args: ['connect', '--help'],
+        });
+    if (!config?.success)
+        next.push({
+            reason: 'Configure the source scope and commands before enabling Studio code editing.',
+            command: 'storystick',
+            args: ['source', 'configure', '--help'],
+        });
+    else
+        next.push({
+            reason: 'Review the committed source before transferring it.',
+            command: 'storystick',
+            args: ['source', 'prepare', '--root', root, '--dry-run', '--json'],
+        });
+    return {
+        root,
+        connection,
+        repository,
+        application: {
+            manifest: pkg !== null,
+            framework: pkg?.dependencies?.next || pkg?.devDependencies?.next ? 'nextjs' : null,
+            scripts: pkg?.scripts && typeof pkg.scripts === 'object' ? Object.keys(pkg.scripts).sort() : [],
+            packageManager: typeof pkg?.packageManager === 'string' &&
+                /^(pnpm|npm|yarn|bun)@[\w.+-]+$/.test(pkg.packageManager)
+                ? pkg.packageManager
+                : null,
+        },
+        source: config?.success
+            ? {
+                configured: true,
+                scope: config.data.scope,
+                schemaVersion: config.data.schemaVersion,
+                checks: config.data.recipe.checks.map((check) => check.name),
+                previewPort: config.data.recipe.preview.port,
+            }
+            : { configured: false },
+        hosting: vercel &&
+            /^prj_[a-zA-Z0-9]+$/.test(vercel.projectId) &&
+            /^team_[a-zA-Z0-9]+$/.test(vercel.orgId)
+            ? {
+                provider: 'vercel',
+                projectId: vercel.projectId,
+                teamId: vercel.orgId,
+                status: 'local-link-only',
+            }
+            : null,
+        issues,
+        next,
+    };
+}
+/** A reviewed proposal becomes the local configuration. Never overwrite another
+ * configuration on retry, including one belonging to an active release. */
+export function configureSource(root, proposalPath) {
+    return saveSourceConfiguration(root, JSON.parse(readFileSync(resolve(root, proposalPath), 'utf8')));
+}
+function saveSourceConfiguration(root, proposal) {
+    const configuration = sourceConfiguration.parse(proposal);
+    const destination = resolve(root, '.storystick/source.json');
+    if (existsSync(destination)) {
+        const existing = sourceConfiguration.parse(JSON.parse(readFileSync(destination, 'utf8')));
+        if (JSON.stringify(existing) !== JSON.stringify(configuration))
+            throw Error('Source configuration already exists. Review and edit .storystick/source.json directly; it was not overwritten.');
+        return { path: destination, configured: true, changed: false };
+    }
+    mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, JSON.stringify(configuration, null, 2) + '\n', {
+        flag: 'wx',
+        mode: 0o600,
+    });
+    return { path: destination, configured: true, changed: true };
+}
+/** A deliberately narrow preset. Monorepos keep their explicit dependency scope. */
+export function configureNextSource(root, schemaFile) {
+    root = resolve(root);
+    const repo = inspectRepository(root);
+    if (!repo || realpathSync(repo.root) !== realpathSync(root))
+        throw Error('Run the Next.js preset at the Git root. For a monorepo, use --config with an explicit source scope.');
+    const compiled = JSON.parse(readFileSync(resolve(root, schemaFile), 'utf8'));
+    if (compiled.formatVersion !== 1 || typeof compiled.version !== 'string' || !compiled.stories)
+        throw Error('Use the output of storystick schema for --schema.');
+    return saveSourceConfiguration(root, nextSourceConfiguration({
+        manifest: JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8')),
+        files: readdirSync(root),
+        schemaVersion: compiled.version,
+    }));
+}

package/dist/source-git.d.ts

@@ -0,0 +1,36 @@
+import { type SourceEntry } from '@storystick/source/archive';
+import { type SourceScope, type SourceChange } from '@storystick/source/manifest';
+export declare const repositoryRoot: (root: string) => string;
+export declare function inspectRepository(root: string): {
+    root: string;
+    commit: string | null;
+    dirty: boolean;
+    remotes: string[];
+} | null;
+export declare function captureCommit(root: string, revision: string, rawScope: SourceScope): {
+    commit: string;
+    scope: {
+        appRoot: string;
+        include: string[];
+        exclude: string[];
+    };
+    files: {
+        path: string;
+        mode: number;
+        content: Buffer<ArrayBuffer>;
+        digest: string;
+    }[];
+    revision: string;
+};
+/** Schema provenance uses this same byte/mode identity. It is a working capture,
+ * not a claim that those bytes have been imported into a remote workspace. */
+export declare function captureWorkingSource(root: string, scope: SourceScope): SourceEntry[];
+/** Produces an ordinary independent Git checkout. The original index, refs,
+ * untracked files and dirty worktree are never modified, including on conflict. */
+export declare function integrateSource(root: string, out: string, change: SourceChange, base: SourceEntry[], result: SourceEntry[], localRef?: string): {
+    status: string;
+    localCommit: string;
+    changeId: string;
+    conflicts: string[];
+    destination: string;
+};

package/dist/source-git.js

@@ -0,0 +1,197 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, existsSync, renameSync, writeFileSync, readFileSync, lstatSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { sourceDigest, sourceRevision } from '@storystick/source/archive';
+import { sourceChangeIdentity, inSourceScope, sourcePath, sourceScope, sourceManifest, MAX_SOURCE_BYTES, MAX_SOURCE_FILES } from '@storystick/source/manifest';
+// No user-global hooks, filters, external diff drivers or inherited Git target.
+const gitEnv = () => ({ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+    GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_AUTHOR_NAME: 'Storystick', GIT_AUTHOR_EMAIL: 'source@storystick.invalid',
+    GIT_COMMITTER_NAME: 'Storystick', GIT_COMMITTER_EMAIL: 'source@storystick.invalid',
+});
+function git(root, args, input, env, allowFailure = false) {
+    const result = spawnSync('git', ['-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', '-c', 'core.autocrlf=false', '-c', 'core.attributesFile=/dev/null', ...args], {
+        cwd: root, env: { ...gitEnv(), ...env }, input, maxBuffer: MAX_SOURCE_BYTES + 16 * 1024 * 1024, timeout: 60_000,
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0 && !allowFailure)
+        throw Error(`Git operation failed (${args[0]}): ${result.stderr.toString().slice(0, 2000)}`);
+    return result;
+}
+const text = (root, args, input, env) => git(root, args, input, env).stdout.toString().trim();
+export const repositoryRoot = (root) => text(root, ['rev-parse', '--show-toplevel']);
+export function inspectRepository(root) {
+    const probe = git(root, ['rev-parse', '--show-toplevel'], undefined, undefined, true);
+    if (probe.status !== 0)
+        return null;
+    const directory = probe.stdout.toString().trim();
+    const head = git(directory, ['rev-parse', '--verify', 'HEAD'], undefined, undefined, true);
+    return {
+        root: directory,
+        commit: head.status === 0 ? head.stdout.toString().trim() : null,
+        dirty: git(directory, ['status', '--porcelain', '-z']).stdout.length > 0,
+        // Remote URLs may embed credentials. Their names are enough for discovery.
+        remotes: text(directory, ['remote']).split('\n').filter(Boolean),
+    };
+}
+function treeEntries(root, commit) {
+    const raw = git(root, ['ls-tree', '-rz', '--full-tree', commit]).stdout;
+    if (!Buffer.from(raw.toString()).equals(raw))
+        throw Error('Source paths must be UTF-8.');
+    return raw.toString().split('\0').filter(Boolean).map(line => {
+        const match = /^(\d{6}) (blob|commit) ([a-f0-9]+)\t(.+)$/s.exec(line);
+        if (!match)
+            throw Error('Unsupported Git tree entry.');
+        return { path: match[4], mode: parseInt(match[1], 8), oid: match[3] };
+    });
+}
+function checkedEntries(root, commit, scope) {
+    const entries = treeEntries(root, commit).filter(file => inSourceScope(file.path, scope));
+    if (entries.length > MAX_SOURCE_FILES)
+        throw Error('Source contains too many files.');
+    for (const file of entries) {
+        sourcePath(file.path);
+        if (![0o100644, 0o100755].includes(file.mode))
+            throw Error(`Unsupported link or submodule: ${file.path}`);
+    }
+    const scratch = mkdtempSync(join(tmpdir(), 'storystick-attributes-'));
+    try {
+        const env = { GIT_INDEX_FILE: join(scratch, 'index') };
+        git(root, ['read-tree', commit], undefined, env);
+        const attrs = git(root, ['check-attr', '--cached', '-z', '--stdin', 'filter', 'working-tree-encoding', 'eol', 'text'], entries.map(f => f.path + '\0').join(''), env).stdout.toString().split('\0');
+        for (let i = 0; i + 2 < attrs.length; i += 3) {
+            if (!['unspecified', 'unset'].includes(attrs[i + 2]))
+                throw Error(`Unsupported Git attribute ${attrs[i + 1]} on ${attrs[i]}.`);
+        }
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+    return entries;
+}
+export function captureCommit(root, revision, rawScope) {
+    root = repositoryRoot(root);
+    const scope = sourceScope.parse(rawScope);
+    const commit = text(root, ['rev-parse', '--verify', '--end-of-options', `${revision}^{commit}`]);
+    const entries = checkedEntries(root, commit, scope);
+    const result = entries.length ? git(root, ['cat-file', '--batch'], entries.map(file => file.oid + '\n').join('')).stdout : Buffer.alloc(0);
+    let offset = 0, total = 0;
+    const files = entries.map(file => {
+        const newline = result.indexOf(10, offset);
+        const header = result.subarray(offset, newline).toString().split(' ');
+        const size = Number(header[2]);
+        total += size;
+        if (header[0] !== file.oid || header[1] !== 'blob' || !Number.isSafeInteger(size) || size < 0 || total > MAX_SOURCE_BYTES)
+            throw Error('Invalid or oversized Git source.');
+        const content = result.subarray(newline + 1, newline + 1 + size);
+        offset = newline + size + 2;
+        if (content.length !== size || result[offset - 1] !== 10)
+            throw Error('Truncated Git source.');
+        if (content.subarray(0, 100).toString().startsWith('version https://git-lfs.github.com/spec/'))
+            throw Error(`Git LFS is not supported: ${file.path}`);
+        return { path: file.path, mode: file.mode === 0o100755 ? 0o755 : 0o644, content, digest: sourceDigest(content) };
+    });
+    sourceManifest(files);
+    return { commit, scope, files, revision: sourceRevision(files) };
+}
+/** Schema provenance uses this same byte/mode identity. It is a working capture,
+ * not a claim that those bytes have been imported into a remote workspace. */
+export function captureWorkingSource(root, scope) {
+    root = repositoryRoot(root);
+    const paths = [...new Set(git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']).stdout.toString().split('\0').filter(Boolean))];
+    let total = 0;
+    const files = paths.filter(path => inSourceScope(path, scope)).flatMap(path => {
+        // Connection/runtime files are never part of source provenance.
+        if (path.split('/').some(part => part === '.storystick' || part.startsWith('.env')))
+            return [];
+        sourcePath(path);
+        const absolute = resolve(root, path);
+        if (!existsSync(absolute))
+            return [];
+        for (let parent = absolute; parent !== root; parent = dirname(parent))
+            if (lstatSync(parent).isSymbolicLink())
+                throw Error(`Unsupported symlink: ${path}`);
+        const stat = lstatSync(absolute);
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw Error(`Unsupported source file: ${path}`);
+        total += stat.size;
+        if (total > MAX_SOURCE_BYTES)
+            throw Error('Source is too large.');
+        const content = readFileSync(absolute);
+        return [{ path, content, mode: stat.mode & 0o111 ? 0o755 : 0o644, digest: sourceDigest(content) }];
+    });
+    sourceManifest(files);
+    return files;
+}
+function projectedTree(root, local, files, scope, index) {
+    const env = { GIT_INDEX_FILE: index };
+    git(root, ['read-tree', local], undefined, env);
+    const current = treeEntries(root, local).filter(f => inSourceScope(f.path, scope));
+    const zero = '0'.repeat(text(root, ['rev-parse', '--show-object-format']) === 'sha256' ? 64 : 40);
+    const updates = current.map(file => `0 ${zero}\t${file.path}\0`);
+    for (const file of files) {
+        if (!inSourceScope(file.path, scope))
+            throw Error('Artifact contains a path outside its scope.');
+        const oid = text(root, ['hash-object', '-w', '--stdin'], file.content);
+        updates.push(`${file.mode === 0o755 ? '100755' : '100644'} ${oid}\t${file.path}\0`);
+    }
+    git(root, ['update-index', '-z', '--index-info'], updates.join(''), env);
+    return text(root, ['write-tree'], undefined, env);
+}
+/** Produces an ordinary independent Git checkout. The original index, refs,
+ * untracked files and dirty worktree are never modified, including on conflict. */
+export function integrateSource(root, out, change, base, result, localRef = 'HEAD') {
+    root = realpathSync(repositoryRoot(root));
+    out = join(realpathSync(dirname(resolve(out))), basename(out));
+    if (existsSync(out))
+        throw Error(`Destination already exists; inspect it before retrying: ${out}`);
+    if (out === root || out.startsWith(root + '/'))
+        throw Error('Choose a destination outside the original checkout.');
+    const version = text(root, ['--version']).match(/(\d+)\.(\d+)/);
+    if (!version || Number(version[1]) < 2 || Number(version[1]) === 2 && Number(version[2]) < 41)
+        throw Error('Source integration requires Git 2.41 or later.');
+    if (sourceRevision(base) !== change.base.revision || sourceRevision(result) !== change.result.revision)
+        throw Error('Artifact source revision mismatch.');
+    const local = captureCommit(root, localRef, change.scope).commit;
+    const stage = mkdtempSync(join(dirname(out), '.storystick-integrate-'));
+    try {
+        git(root, ['-c', 'init.templateDir=', 'clone', '--local', '--no-hardlinks', '--no-checkout', '--', root, stage]);
+        const index = join(stage, '.git', 'source-index');
+        const baseTree = projectedTree(stage, local, base, change.scope, index);
+        const resultTree = projectedTree(stage, local, result, change.scope, index);
+        checkedEntries(stage, baseTree, change.scope);
+        checkedEntries(stage, resultTree, change.scope);
+        const b = text(stage, ['commit-tree', baseTree, '-m', 'Source import base']);
+        const r = text(stage, ['commit-tree', resultTree, '-p', b, '-m', 'Remote source result']);
+        const merge = git(stage, ['merge-tree', '--write-tree', '-z', '--no-messages', `--merge-base=${b}`, local, r], undefined, undefined, true);
+        if (merge.status !== 0 && merge.status !== 1)
+            throw Error('Git could not compute the source integration.');
+        const parts = merge.stdout.toString().split('\0'), tree = parts.shift();
+        if (!/^[a-f0-9]{40,64}$/.test(tree))
+            throw Error('Git returned an invalid merge tree.');
+        const stages = parts.filter(line => /^\d{6} [a-f0-9]+ [123]\t/.test(line));
+        const conflicts = [...new Set(stages.map(line => line.slice(line.indexOf('\t') + 1)))].sort();
+        if (merge.status === 1 && !conflicts.length)
+            throw Error('Git returned a conflict without file stages.');
+        git(stage, ['symbolic-ref', 'HEAD', 'refs/heads/storystick/source']);
+        git(stage, ['update-ref', 'HEAD', local]);
+        git(stage, ['read-tree', tree]);
+        git(stage, ['checkout-index', '-a']);
+        if (conflicts.length) {
+            const zero = '0'.repeat(local.length);
+            git(stage, ['update-index', '-z', '--index-info'], conflicts.map(path => `0 ${zero}\t${path}\0`).join('') + stages.map(line => line + '\0').join(''));
+        }
+        rmSync(index, { force: true });
+        const receipt = { status: conflicts.length ? 'conflicted' : 'ready', localCommit: local,
+            changeId: sourceDigest(sourceChangeIdentity(change)), conflicts, destination: out };
+        writeFileSync(join(stage, '.git', 'storystick-source.json'), JSON.stringify(receipt, null, 2) + '\n');
+        renameSync(stage, out);
+        return receipt;
+    }
+    finally {
+        if (existsSync(stage))
+            rmSync(stage, { recursive: true, force: true });
+    }
+}

package/dist/starter-resolver.d.ts

@@ -0,0 +1,82 @@
+export declare const DEFAULT_STARTER_ID: "minimal-next";
+export declare const DEFAULT_STARTER_CATALOG_URL = "https://starters.storystick.app/catalog.json";
+export declare const STARTER_CATALOG_ENV = "STORYSTICK_STARTER_CATALOG_URL";
+export declare const PREPARED_STARTER_DIRECTORY: string;
+export declare const MATERIALIZED_STARTER_MARKER: string;
+export interface StarterOverlayPath {
+    readonly from: string;
+    readonly to: string;
+}
+export interface StarterManifest {
+    readonly version: 2;
+    readonly id: string;
+    readonly release: string;
+    readonly framework: 'next' | 'astro';
+    readonly integration: {
+        readonly contract: 'next-app-router' | 'astro-native';
+        readonly version: 1;
+        readonly routeStoryTypes: readonly string[];
+        readonly fields: {
+            readonly title: string;
+            readonly description: string;
+            readonly slices: string;
+            readonly siteSettings: string;
+            readonly siteName: string;
+            readonly siteDescription: string;
+        };
+        readonly existingNext?: readonly StarterOverlayPath[];
+    };
+}
+export interface StarterArtifactIdentity {
+    readonly id: string;
+    readonly release: string;
+    readonly framework: 'next' | 'astro';
+    readonly source: {
+        readonly provider: 'archive';
+        readonly url: string;
+        readonly integrity: string;
+    };
+    readonly integrity: string;
+    readonly localDirectory?: string;
+}
+export interface StarterCatalogEntry extends StarterArtifactIdentity {
+    readonly label: string;
+    readonly description: string;
+    readonly capabilities: readonly string[];
+}
+export interface StarterCatalog {
+    readonly version: 2;
+    readonly default: string;
+    readonly starters: readonly StarterCatalogEntry[];
+}
+export interface LoadStarterCatalogOptions {
+    readonly startDir?: string;
+    readonly catalogUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+    readonly signal?: AbortSignal;
+}
+export interface PrepareStarterOptions {
+    readonly entry: StarterArtifactIdentity;
+    readonly targetDir: string;
+    readonly startDir?: string;
+    readonly fetchImpl?: typeof fetch;
+    readonly signal?: AbortSignal;
+    readonly onManifest?: (manifest: StarterManifest) => void;
+}
+export declare function loadStarterCatalog(options?: LoadStarterCatalogOptions): Promise<StarterCatalog>;
+export declare function readStarterCatalog(path: string): StarterCatalog;
+export declare function selectStarter(catalog: StarterCatalog, requestedId?: string): StarterCatalogEntry;
+/** A required archive digest pins the bytes independently of the hosting URL. */
+export declare function resolveStarterSource(entry: StarterArtifactIdentity): string;
+export declare function findMonorepoRoot(startDir?: string): string | null;
+export declare function findLocalStarterCatalog(startDir?: string): string | null;
+export declare function findLocalStarter(entry: StarterArtifactIdentity, startDir?: string): string | null;
+/** Fetch, validate, and hash a starter before publishing any of its bytes. */
+export declare function prepareStarter(options: PrepareStarterOptions): Promise<StarterManifest>;
+/** Publish only previously validated bytes into a blank application tree. */
+export declare function ensurePreparedStarterMaterialized(targetDir: string, entry: StarterArtifactIdentity): StarterManifest;
+export declare function readStarterManifest(starterRoot: string): StarterManifest;
+export declare function computeStarterIntegrity(starterRoot: string): string;
+export declare function preparedStarterRoot(targetDir: string): string;
+export declare function listStarterFiles(root: string): string[];
+export declare function copyDirRecursive(source: string, destination: string): void;