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

package/dist/init-scaffold.js

@@ -0,0 +1,439 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { StorystickError } from './cli-error.js';
+const KERNEL_ROOT = fileURLToPath(new URL('../assets/next-v1/', import.meta.url));
+const GITIGNORE_ENTRIES = [
+    'node_modules/',
+    '.next/',
+    '.env.local',
+    'generated/',
+    '.storystick/',
+];
+export function isNextProject(rootDir) {
+    const packageJson = readPackageJson(rootDir);
+    if (packageJson === null)
+        return false;
+    return Boolean(packageJson.dependencies?.next ??
+        packageJson.devDependencies?.next ??
+        packageJson.peerDependencies?.next);
+}
+export function planInitScaffold({ rootDir, starterRoot, manifest, force = false, }) {
+    if (manifest.framework !== 'next')
+        throw new StorystickError('The Next integration kernel cannot be applied to an Astro starter.', { code: 'INIT_FRAMEWORK_MISMATCH', category: 'validation' });
+    const appDir = detectAppDir(rootDir);
+    const componentsDir = appDir.startsWith('src/')
+        ? 'src/components'
+        : 'components';
+    const libDir = appDir.startsWith('src/') ? 'src/lib' : 'lib';
+    const catchAllDir = join(appDir, '[[...pathname]]');
+    const actions = [];
+    actions.push(...planStarterOverlay({
+        rootDir,
+        starterRoot,
+        manifest,
+        componentsDir,
+        force,
+    }));
+    // The customer's native root layout stays at its native location.
+    const rootLayoutPath = join(appDir, 'layout.tsx');
+    const replaceRoot = existsSync(join(rootDir, rootLayoutPath)) && isReplaceableRootLayout(readFileSync(join(rootDir, rootLayoutPath), 'utf8'));
+    actions.push(planKernelFile({ rootDir, path: rootLayoutPath, asset: 'app/layout.tsx', manifest, force: force || replaceRoot, critical: true }));
+    const rootPagePath = join(appDir, 'page.tsx');
+    const rootPageAction = planRootPageConflictAction(rootDir, rootPagePath, force);
+    const canCreateCatchAll = !existsSync(join(rootDir, rootPagePath)) ||
+        rootPageAction?.status === 'delete';
+    if (rootPageAction)
+        actions.push(rootPageAction);
+    actions.push(canCreateCatchAll
+        ? planKernelFile({
+            rootDir,
+            path: join(catchAllDir, 'page.tsx'),
+            asset: 'app/[[...pathname]]/page.tsx',
+            manifest,
+            force,
+            critical: true,
+        })
+        : {
+            kind: 'file',
+            path: join(catchAllDir, 'page.tsx'),
+            status: 'skip',
+            content: renderKernelAsset('app/[[...pathname]]/page.tsx', manifest),
+            reason: `${rootPagePath} conflicts with the optional catch-all; ` +
+                'move it or re-run with --force',
+            critical: true,
+        }, planKernelFile({
+        rootDir,
+        path: join(catchAllDir, 'not-found.tsx'),
+        asset: 'app/[[...pathname]]/not-found.tsx',
+        manifest,
+        force,
+        critical: true,
+    }), planKernelFile({
+        rootDir,
+        path: join(catchAllDir, 'error.tsx'),
+        asset: 'app/[[...pathname]]/error.tsx',
+        manifest,
+        force,
+        critical: true,
+    }), planKernelFile({
+        rootDir,
+        path: join(appDir, 'api', 'storystick', '[...action]', 'route.ts'),
+        asset: 'app/api/storystick/[...action]/route.ts',
+        manifest,
+        force,
+        critical: true,
+    }), planKernelFile({
+        rootDir,
+        path: join(appDir, 'sitemap.ts'),
+        asset: 'app/sitemap.ts',
+        manifest,
+        force,
+        critical: true,
+    }), planKernelFile({
+        rootDir,
+        path: join(libDir, 'site.ts'),
+        asset: 'lib/site.ts',
+        manifest,
+        force,
+        critical: true,
+    }), planNextConfigAction(rootDir, manifest, force), planOptionalGlobalsAction(rootDir, join(appDir, 'globals.css'), manifest), planKernelFile({
+        rootDir,
+        path: '.env.local.example',
+        asset: 'env.local.example',
+        manifest,
+        force,
+    }), planPackageAction(rootDir, starterRoot), planGitignoreAction(rootDir));
+    return { rootDir, appDir, componentsDir, actions };
+}
+export function assertInitScaffoldReady(plan) {
+    const blocked = plan.actions.filter((action) => action.status === 'skip' &&
+        'critical' in action &&
+        action.critical === true &&
+        action.reason !== 'already up to date');
+    if (blocked.length === 0)
+        return;
+    throw new StorystickError(`Storystick cannot safely integrate ${blocked
+        .map((action) => `${action.path}: ${action.reason ?? 'conflict'}`)
+        .join('; ')}`, {
+        code: 'INIT_SCAFFOLD_CONFLICT',
+        category: 'conflict',
+        recoverable: true,
+        payload: { paths: blocked.map((action) => action.path) },
+    });
+}
+export function writeInitScaffold(plan) {
+    assertInitScaffoldReady(plan);
+    for (const action of plan.actions) {
+        if (action.status === 'skip')
+            continue;
+        const absolute = join(plan.rootDir, action.path);
+        if (action.kind === 'delete') {
+            rmSync(absolute, { force: true });
+            continue;
+        }
+        mkdirSync(dirname(absolute), { recursive: true });
+        writeFileSync(absolute, action.content, 'utf8');
+    }
+}
+export function summarizeInitScaffold(plan) {
+    return {
+        changed: plan.actions.filter((action) => action.status !== 'skip').length,
+        skipped: plan.actions.filter((action) => action.status === 'skip'),
+    };
+}
+export function renderKernelAsset(asset, manifest) {
+    const fields = manifest.integration.fields;
+    const replacements = {
+        '{{ROUTE_STORY_TYPES}}': JSON.stringify(manifest.integration.routeStoryTypes),
+        '{{TITLE_FIELD}}': JSON.stringify(fields.title),
+        '{{DESCRIPTION_FIELD}}': JSON.stringify(fields.description),
+        '{{SLICES_FIELD}}': JSON.stringify(fields.slices),
+        '{{SITE_SETTINGS_STORY}}': JSON.stringify(fields.siteSettings),
+        '{{SITE_NAME_FIELD}}': fields.siteName,
+        '{{SITE_DESCRIPTION_FIELD}}': fields.siteDescription,
+    };
+    let source = readFileSync(join(KERNEL_ROOT, asset), 'utf8');
+    for (const [token, value] of Object.entries(replacements)) {
+        source = source.replaceAll(token, value);
+    }
+    if (/\{\{[A-Z_]+\}\}/u.test(source)) {
+        throw new StorystickError(`Unresolved integration token in ${asset}.`, {
+            code: 'INIT_KERNEL_INVALID',
+            category: 'system',
+        });
+    }
+    return source;
+}
+function planStarterOverlay({ rootDir, starterRoot, manifest, componentsDir, force, }) {
+    const actions = [];
+    const destinations = new Map();
+    for (const mapping of manifest.integration.existingNext ?? []) {
+        const source = join(starterRoot, mapping.from);
+        if (!existsSync(source) || !lstatSync(source).isDirectory()) {
+            throw new StorystickError(`Starter overlay source must be a directory: ${mapping.from}`, { code: 'STARTER_OVERLAY_MISSING', category: 'validation' });
+        }
+        const destination = mapping.to === 'stories'
+            ? 'stories'
+            : join(componentsDir, relative('components', mapping.to));
+        for (const file of listFiles(source)) {
+            const path = join(destination, file);
+            const previous = destinations.get(path);
+            if (previous) {
+                throw new StorystickError(`Starter overlay mappings "${previous}" and "${mapping.from}" both publish ${path}.`, { code: 'STARTER_OVERLAY_COLLISION', category: 'validation' });
+            }
+            destinations.set(path, mapping.from);
+            actions.push(planFileAction({
+                rootDir,
+                path,
+                content: readFileSync(join(source, file), 'utf8'),
+                force,
+                critical: true,
+            }));
+        }
+    }
+    return actions;
+}
+function planKernelFile({ rootDir, path, asset, manifest, force, critical = false, }) {
+    return planFileAction({
+        rootDir,
+        path,
+        content: renderKernelAsset(asset, manifest),
+        force,
+        critical,
+    });
+}
+function planFileAction({ rootDir, path, content, force, critical = false, }) {
+    const absolute = join(rootDir, path);
+    if (!existsSync(absolute)) {
+        return { kind: 'file', path, status: 'create', content, critical };
+    }
+    const current = readFileSync(absolute, 'utf8');
+    if (current === content) {
+        return {
+            kind: 'file',
+            path,
+            status: 'skip',
+            content,
+            reason: 'already up to date',
+            critical,
+        };
+    }
+    if (force) {
+        return { kind: 'file', path, status: 'overwrite', content, critical };
+    }
+    return {
+        kind: 'file',
+        path,
+        status: 'skip',
+        content,
+        reason: 'exists; re-run with --force to overwrite',
+        critical,
+    };
+}
+function planNextConfigAction(rootDir, manifest, _force) {
+    const existing = findExistingNextConfig(rootDir);
+    if (existing)
+        return { kind: 'file', path: existing, status: 'skip', content: readFileSync(join(rootDir, existing), 'utf8'), reason: 'native Next configuration preserved', critical: false };
+    return { kind: 'file', path: 'next.config.ts', status: 'create', content: renderKernelAsset('next.config.ts', manifest), critical: false };
+}
+function planOptionalGlobalsAction(rootDir, path, manifest) {
+    const content = renderKernelAsset('globals.css', manifest);
+    const absolute = join(rootDir, path);
+    return existsSync(absolute)
+        ? {
+            kind: 'file',
+            path,
+            status: 'skip',
+            content: readFileSync(absolute, 'utf8'),
+            reason: 'customer styles preserved',
+        }
+        : { kind: 'file', path, status: 'create', content };
+}
+function planRootPageConflictAction(rootDir, path, force) {
+    const absolute = join(rootDir, path);
+    if (!existsSync(absolute))
+        return null;
+    const current = readFileSync(absolute, 'utf8');
+    if (force || isCreateNextAppPlaceholderPage(current)) {
+        return {
+            kind: 'delete',
+            path,
+            status: 'delete',
+            reason: 'removed because it conflicts with the Storystick optional catch-all',
+        };
+    }
+    return null;
+}
+function planPackageAction(rootDir, starterRoot) {
+    const path = join(rootDir, 'package.json');
+    const current = readPackageJson(rootDir) ?? {};
+    const next = mergePackageJson(current, starterRoot);
+    const content = `${JSON.stringify(next, null, 2)}\n`;
+    if (!existsSync(path)) {
+        return { kind: 'package', path: 'package.json', status: 'create', content };
+    }
+    if (readFileSync(path, 'utf8') === content) {
+        return {
+            kind: 'package',
+            path: 'package.json',
+            status: 'skip',
+            content,
+            reason: 'already up to date',
+        };
+    }
+    return { kind: 'package', path: 'package.json', status: 'update', content };
+}
+function mergePackageJson(packageJson, starterRoot) {
+    // Both init strategies use the selected, verified artifact's package contract.
+    const starterPackage = readPackageJson(starterRoot);
+    const nextVersion = starterPackage?.dependencies?.['@storystick/next'];
+    const cliVersion = starterPackage?.devDependencies?.['@storystick/cli'];
+    if (typeof nextVersion !== 'string' || !nextVersion.trim() ||
+        typeof cliVersion !== 'string' || !cliVersion.trim()) {
+        throw new StorystickError('Starter must declare @storystick/next and @storystick/cli package versions.', {
+            code: 'STARTER_MANIFEST_INVALID', category: 'validation',
+        });
+    }
+    const scripts = asRecord(packageJson.scripts);
+    const dependencies = asRecord(packageJson.dependencies);
+    const devDependencies = asRecord(packageJson.devDependencies);
+    const imports = asRecord(packageJson.imports);
+    const buildScript = typeof scripts.build === 'string' && scripts.build.length > 0
+        ? scripts.build
+        : 'next build';
+    const generate = 'storystick generate --root . --stories stories';
+    const buildHasGenerate = buildScript.includes('storystick generate') ||
+        buildScript.includes('storystick:generate');
+    return {
+        ...packageJson,
+        imports: {
+            ...imports,
+            '#storystick/*': './generated/storystick/*.ts',
+        },
+        scripts: {
+            ...scripts,
+            'storystick:generate': generate,
+            'storystick:push': 'storystick push --root . --stories stories',
+            'storystick:sync': 'storystick sync --root . --stories stories',
+            build: buildHasGenerate ? buildScript : `${generate} && ${buildScript}`,
+        },
+        dependencies: {
+            ...dependencies,
+            '@storystick/next': dependencies['@storystick/next'] ?? nextVersion,
+        },
+        devDependencies: {
+            ...devDependencies,
+            '@storystick/cli': devDependencies['@storystick/cli'] ?? cliVersion,
+        },
+    };
+}
+function planGitignoreAction(rootDir) {
+    const path = '.gitignore';
+    const absolute = join(rootDir, path);
+    if (!existsSync(absolute)) {
+        return {
+            kind: 'gitignore',
+            path,
+            status: 'create',
+            content: `${GITIGNORE_ENTRIES.join('\n')}\n`,
+        };
+    }
+    const current = readFileSync(absolute, 'utf8');
+    const lines = new Set(current
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter(Boolean));
+    const missing = GITIGNORE_ENTRIES.filter((entry) => !lines.has(entry));
+    if (missing.length === 0) {
+        return {
+            kind: 'gitignore',
+            path,
+            status: 'skip',
+            content: current,
+            reason: 'already up to date',
+        };
+    }
+    const separator = current.length === 0 || current.endsWith('\n') ? '' : '\n';
+    return {
+        kind: 'gitignore',
+        path,
+        status: 'update',
+        content: `${current}${separator}${missing.join('\n')}\n`,
+    };
+}
+function detectAppDir(rootDir) {
+    if (existsSync(join(rootDir, 'src', 'app')))
+        return 'src/app';
+    if (existsSync(join(rootDir, 'app')))
+        return 'app';
+    if (existsSync(join(rootDir, 'src')))
+        return 'src/app';
+    return 'app';
+}
+function findExistingNextConfig(rootDir) {
+    for (const candidate of [
+        'next.config.ts',
+        'next.config.mjs',
+        'next.config.js',
+        'next.config.cjs',
+    ]) {
+        if (existsSync(join(rootDir, candidate)))
+            return candidate;
+    }
+    return null;
+}
+function isDefaultNextConfig(source) {
+    return (source.includes('const nextConfig') &&
+        source.includes('export default nextConfig') &&
+        (/const nextConfig(?::\s*NextConfig)?\s*=\s*\{\s*\}/mu.test(source) ||
+            source.includes('/* config options here */')));
+}
+function isCreateNextAppPlaceholderPage(source) {
+    return (source.includes('export default function Home') &&
+        source.includes('Get started by editing') &&
+        source.includes('next/image'));
+}
+function isReplaceableRootLayout(source) {
+    return ((source.includes('@storystick/next') && source.includes('<Storystick')) ||
+        source.includes('Geist_Mono') ||
+        source.includes('create-next-app') ||
+        (source.includes('Create Next App') &&
+            source.includes('Generated by create next app')));
+}
+function readPackageJson(rootDir) {
+    const path = join(rootDir, 'package.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function asRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    return { ...value };
+}
+function listFiles(root) {
+    const files = [];
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory).sort()) {
+            const absolute = join(directory, entry);
+            const status = lstatSync(absolute);
+            if (status.isSymbolicLink()) {
+                throw new StorystickError(`Starter overlay contains an unsupported link: ${relative(root, absolute)}`, { code: 'STARTER_ARTIFACT_UNSAFE', category: 'validation' });
+            }
+            if (status.isDirectory())
+                visit(absolute);
+            else if (status.isFile()) {
+                files.push(relative(root, absolute).split(sep).join('/'));
+            }
+        }
+    };
+    visit(resolve(root));
+    return files;
+}

package/dist/init.d.ts

@@ -0,0 +1,51 @@
+import { type InitOperationReceipt } from './init-operation.js';
+export interface InitOptions {
+    link?: string;
+    team?: string;
+    newTeam?: string;
+    into?: string;
+    origin?: string;
+    locale?: string;
+    siteUrl?: string;
+    starter?: string;
+    force?: boolean;
+    json?: boolean;
+    /** @internal deterministic idempotency seam. */
+    operationId?: string;
+}
+export interface EligibleProjectTeam {
+    shortId: string;
+    name: string;
+    role: 'owner' | 'admin';
+    isPersonal: boolean;
+}
+interface ProjectTeamSelectionOptions {
+    requestedShortId?: string;
+    newTeamName?: string;
+    interactive: boolean;
+    prompt?: (message: string, choices: Array<{
+        value: string;
+        name: string;
+        description: string;
+    }>) => Promise<string>;
+}
+export declare function runInit(projectNameArg?: string, options?: InitOptions): Promise<void>;
+export declare function sanitizedInstallEnvironment(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function installDependencies(targetDir: string, signal?: AbortSignal): Promise<void>;
+export declare function relativeTarget(targetDir: string, cwd?: string): string;
+export declare function selectEligibleProjectTeam(teams: EligibleProjectTeam[], options: ProjectTeamSelectionOptions): Promise<EligibleProjectTeam | {
+    newTeamName: string;
+}>;
+export declare function fetchEligibleProjectTeams(signal?: AbortSignal, rootDir?: string): Promise<EligibleProjectTeam[]>;
+export declare function printInitOutro(args: {
+    dirName: string;
+    shortId: string;
+    projectName: string;
+    team?: {
+        shortId: string;
+        name: string;
+    };
+    linked?: boolean;
+    receipt?: InitOperationReceipt;
+}): void;
+export {};