@minamocms/framework 0.0.0-stage → 0.10.1

package/dist/create-site/generate-site.d.ts

@@ -0,0 +1,12 @@
+export declare const TEMPLATE_ROOT: string;
+export declare function generateToken(): {
+    raw: string;
+    hash: string;
+};
+export declare const SERVER_JS = "import { startServer } from '@minamocms/framework';\nimport { join } from 'node:path';\n\nawait startServer(join(import.meta.dirname, '..'), { tunnel: process.argv.includes('--tunnel') });\n";
+export declare const SCAFFOLD_SCRIPTS: Record<string, string>;
+export declare class ScaffoldError extends Error {
+}
+export declare function scaffoldSite(targetDir: string): {
+    raw: string;
+};

package/dist/create-site/generate-site.js

@@ -0,0 +1,168 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { CHECKPOINT_AUTHOR } from "../services/checkpoint.js";
+import { commitPaths } from "../services/git.js";
+import { PACKAGE_NAME } from "../upgrade/package-names.js";
+// This file's own bundled template (dist/create-site/template, copied
+// there by `npm run build`'s cp step) - the agent's own asset, not
+// site data, matching validation.ts's/capabilities.ts's existing
+// import.meta.dirname-relative pattern for the agent's own bundled
+// files (see test/static/static-analysis.test.ts's B1 allowlist).
+export const TEMPLATE_ROOT = join(import.meta.dirname, 'template');
+// The agent's own bundled package.json, reused for the exact version
+// to pin the scaffold's dependency to - never a second hardcoded
+// literal, same reasoning as capabilities.ts's readAgentVersion.
+function readAgentVersion() {
+    const packageJsonPath = join(import.meta.dirname, '..', '..', 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    return packageJson.version ?? '0.0.0';
+}
+function sanitisePackageName(dirName) {
+    const cleaned = dirName.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+    return cleaned.length > 0 ? cleaned : 'my-site';
+}
+export function generateToken() {
+    const raw = randomBytes(32).toString('hex');
+    const hash = createHash('sha256').update(raw).digest('hex');
+    return { raw, hash };
+}
+// server.js lives in vhost/, one level below the real site root - it
+// states its own fixed, known relationship to its sibling directory
+// rather than the agent inferring anything (constraint 2 stays intact:
+// the site root is always explicit, never assumed from the agent's own
+// location).
+export const SERVER_JS = `import { startServer } from '${PACKAGE_NAME}';
+import { join } from 'node:path';
+
+await startServer(join(import.meta.dirname, '..'), { tunnel: process.argv.includes('--tunnel') });
+`;
+// The scripts every site's vhost/package.json gets. The CMS owns these:
+// npm run upgrade puts them back as the new version defines them.
+// "start" matters beyond convenience: several PaaS platforms
+// auto-detect and run `npm start` by default for a Node app
+// with no other deploy config - without this, a site pushed
+// straight to one of those (no Dockerfile in the loop) simply
+// wouldn't boot. "tunnel" mirrors the --tunnel flag create-site
+// already tells the operator about in its own next-steps output.
+// "dev" is Node's own --watch-path, not custom fs-watching code
+// - confirmed empirically that it both picks up changes to a
+// plain file under a watched directory that's never imported
+// (theme/*.liquid is only ever read via readFileSync) and sends
+// a real SIGTERM on restart, which server.js's own shutdown
+// handling already listens for. "../theme" because npm run dev
+// runs with cwd vhost/, a sibling of theme/. Deliberately not
+// content/ - that's already read fresh on every request, so
+// watching it would only cause pointless restarts on every
+// content edit. "check" is check-site, the package's own
+// installed CLI bin - runs from vhost/ (site-check/cli.ts's own
+// assumed cwd relationship), same pattern as start/tunnel/dev.
+export const SCAFFOLD_SCRIPTS = {
+    start: 'node server.js',
+    tunnel: 'node server.js --tunnel',
+    dev: 'node --watch-path=../theme server.js',
+    check: 'check-site',
+    // seed-media is the package's own installed CLI bin, exposed
+    // as a script for exactly the same reason check is: there is
+    // no package.json or node_modules at the SITE root, only here
+    // in vhost/, so the obvious-looking `npx seed-media` run from
+    // the site directory resolves nothing locally, goes to the
+    // public registry for a package by that name and dies with
+    // E404 - while still exiting 0. That is not hypothetical: it
+    // is what sent a generated site's images into theme/root/
+    // instead of media/. Run it from here as
+    // `npm run seed-media -- .. <file>`.
+    'seed-media': 'seed-media',
+    // Stops the site from any terminal, not only the one it was
+    // started in (stop-site, via vhost/data/server.pid).
+    stop: 'stop-site',
+    // Copies a running site's content and media into this one
+    // (pull-site): `npm run pull`, which asks for the address and token.
+    pull: 'pull-site',
+    // Sends changes made here since the last pull back to that
+    // live site (push-site), refusing to overwrite anything
+    // edited there since, and only after typing its address.
+    push: 'push-site',
+    // Upgrades the CMS itself (upgrade-site): shows what's new, installs
+    // it, and updates the files in vhost/ that belong to the CMS.
+    upgrade: 'upgrade-site',
+};
+export class ScaffoldError extends Error {
+}
+// A standalone, one-shot CLI operation - no running server exists yet
+// for enqueue()'s serialisation to matter, and this whole function
+// runs synchronously start to finish, so there's no concurrent-write
+// hazard to guard against.
+export function scaffoldSite(targetDir) {
+    if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+        throw new ScaffoldError(`"${targetDir}" already exists and is not empty`);
+    }
+    mkdirSync(targetDir, { recursive: true });
+    // The static theme/content template, copied verbatim except its own
+    // "gitignore"/"dockerignore" (no leading dot - a literal .gitignore
+    // or .dockerignore inside the template tree would be silently
+    // dropped by npm pack's own packlist logic, verified empirically
+    // before this was written).
+    cpSync(TEMPLATE_ROOT, targetDir, {
+        recursive: true,
+        filter: (source) => basename(source) !== 'gitignore' && basename(source) !== 'dockerignore',
+    });
+    cpSync(join(TEMPLATE_ROOT, 'gitignore'), join(targetDir, '.gitignore'));
+    cpSync(join(TEMPLATE_ROOT, 'dockerignore'), join(targetDir, '.dockerignore'));
+    // content/drafts/ starts empty - not part of the static template
+    // (nothing to copy), created directly so a fresh site has somewhere
+    // to write its first draft immediately. Nested inside content/, not
+    // a sibling of it - see config.ts's own comment for why.
+    mkdirSync(join(targetDir, 'content', 'drafts'), { recursive: true });
+    // media/ also starts empty, also created directly (no template
+    // content to copy - see config.ts's own comment for why this is a
+    // sibling of content/theme/vhost, not nested under content/). Not
+    // passed to commitPaths below: media is never git-tracked
+    // (constraint 2), even at scaffold time - an empty directory has
+    // nothing to commit anyway (git doesn't track empty directories), so
+    // this omission is a non-issue mechanically, but it's deliberate,
+    // not an oversight, should anyone go looking for why it's absent
+    // from that list.
+    mkdirSync(join(targetDir, 'media'), { recursive: true });
+    // vhost/: the site's own serving configuration (package.json,
+    // server.js, site.config.json), matching a real vhost's own scope in
+    // hosting terms - never a sibling of content/theme.
+    const vhostDir = join(targetDir, 'vhost');
+    mkdirSync(vhostDir, { recursive: true });
+    // A zero-token site fails closed on every write route (401) - not
+    // usable for editing at all. Generated fresh per scaffold, printed
+    // once, never written to disk - matches every other write-capable
+    // identity in this codebase never depending on a value the operator
+    // could lose or that leaks into version control.
+    const token = generateToken();
+    writeFileSync(join(vhostDir, 'site.config.json'), JSON.stringify({
+        // Written explicitly, matching server-config.ts's own
+        // DEFAULT_PORT, rather than left absent - a real value here
+        // is a visible, editable config knob; an absent key is
+        // invisible until something else is already using the
+        // default port, at which point the failure is a raw
+        // EADDRINUSE crash instead of an obvious setting to change.
+        port: 3000,
+        tokens: [{ hash: token.hash, scopes: ['content', 'theme', 'media'] }],
+    }, null, 2));
+    const packageName = sanitisePackageName(basename(targetDir));
+    writeFileSync(join(vhostDir, 'package.json'), JSON.stringify({
+        name: packageName,
+        version: '0.0.0',
+        private: true,
+        type: 'module',
+        scripts: SCAFFOLD_SCRIPTS,
+        dependencies: {
+            // Pinned exact, never a ^range - at v0.x even a minor bump
+            // can be breaking (build plan's own word is "pinned").
+            [PACKAGE_NAME]: readAgentVersion(),
+        },
+    }, null, 2));
+    writeFileSync(join(vhostDir, 'server.js'), SERVER_JS);
+    // runStartupChecks hard-fails not-a-git-repo otherwise - a scaffold
+    // without a real git repo cannot boot at all.
+    execFileSync('git', ['init', '--quiet'], { cwd: targetDir });
+    commitPaths(targetDir, ['theme', 'content', 'vhost', 'AGENTS.md', '.gitignore', '.dockerignore'], 'chore: initial scaffold', CHECKPOINT_AUTHOR);
+    return { raw: token.raw };
+}

package/dist/create-site/mint-token-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/create-site/mint-token-cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { MintTokenError, mintToken, parseScopes } from "./mint-token.js";
+const targetArg = process.argv[2];
+const scopesFlagIndex = process.argv.indexOf('--scopes');
+const scopesArg = scopesFlagIndex !== -1 ? process.argv[scopesFlagIndex + 1] : undefined;
+if (!targetArg) {
+    console.error('Usage: mint-token <site-directory> [--scopes content,theme,media]');
+    process.exit(1);
+}
+try {
+    const scopes = parseScopes(scopesArg);
+    const siteDir = resolve(process.cwd(), targetArg);
+    const { raw } = mintToken(siteDir, scopes);
+    console.log('New API token (save this now - it will not be shown again):');
+    console.log(`  ${raw}`);
+    console.log('');
+    console.log(`Scopes: ${scopes.join(', ')}`);
+}
+catch (error) {
+    if (error instanceof MintTokenError) {
+        console.error(error.message);
+        process.exit(1);
+    }
+    throw error;
+}

package/dist/create-site/mint-token.d.ts

@@ -0,0 +1,7 @@
+import type { Scope } from '../server-config.ts';
+export declare class MintTokenError extends Error {
+}
+export declare function parseScopes(raw: string | undefined): Scope[];
+export declare function mintToken(siteDir: string, scopes: Scope[]): {
+    raw: string;
+};

package/dist/create-site/mint-token.js

@@ -0,0 +1,49 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CHECKPOINT_AUTHOR } from "../services/checkpoint.js";
+import { commitPaths } from "../services/git.js";
+import { generateToken } from "./generate-site.js";
+export class MintTokenError extends Error {
+}
+const VALID_SCOPES = new Set(['content', 'theme', 'media']);
+export function parseScopes(raw) {
+    if (!raw) {
+        return ['content', 'theme', 'media'];
+    }
+    const scopes = raw.split(',').map((scope) => scope.trim());
+    for (const scope of scopes) {
+        if (!VALID_SCOPES.has(scope)) {
+            throw new MintTokenError(`Unknown scope "${scope}" - valid scopes are content, theme, media`);
+        }
+    }
+    return scopes;
+}
+// A standalone CLI operation against an operator-supplied site
+// directory, same category as scaffoldSite - not a web request's
+// :path, so sanitisePath's traversal concern doesn't apply here.
+export function mintToken(siteDir, scopes) {
+    const configPath = join(siteDir, 'vhost', 'site.config.json');
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf-8');
+    }
+    catch (error) {
+        throw new MintTokenError(`Could not read ${configPath} - is "${siteDir}" a real site created by create-site?`, {
+            cause: error,
+        });
+    }
+    let config;
+    try {
+        config = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new MintTokenError(`${configPath} is not valid JSON`, { cause: error });
+    }
+    const token = generateToken();
+    const tokens = Array.isArray(config.tokens) ? config.tokens : [];
+    tokens.push({ hash: token.hash, scopes });
+    config.tokens = tokens;
+    writeFileSync(configPath, JSON.stringify(config, null, 2));
+    commitPaths(siteDir, ['vhost/site.config.json'], 'chore: mint a new API token', CHECKPOINT_AUTHOR);
+    return { raw: token.raw };
+}