@haystackeditor/cli 0.24.1 → 0.25.1

package/dist/capture/adapters/client-routes.js

@@ -0,0 +1,383 @@
+/**
+ * Route lists of single-page apps whose router is configured in code (CAPTURE-V1 rule 4): React Router's library mode
+ * (createBrowserRouter / createHashRouter / useRoutes route objects, and <Routes><Route> JSX) and Vue Router
+ * (createRouter({ history, routes })). Read statically from the app's source, through same-file consts and relative or
+ * aliased imports; a route whose path is not a literal is a manual step, never a guess. Each route's source is the file
+ * of the component it renders (where blast radius lands), else the file that declares it.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { importSourceOf, jsxName, keyName, literalValue, parseFile, readPathAliases, resolveImport, topLevelConst, UNREADABLE, unwrapTs, walk } from '../js-ast.js';
+import { repoPath } from '../project.js';
+import { paramName, ruleFor } from '../route-pattern.js';
+import { reactRouterSegments } from './react-router.js';
+import { filesUnder } from './files.js';
+class Unreadable extends Error {
+}
+function sourceFiles(dir) {
+    const parsed = [];
+    for (const file of filesUnder(dir)) {
+        if (!/\.(m?[jt]sx?)$/.test(file) || /(^|\/)(__tests__|__mocks__)\//.test(file) || /\.(test|spec|stories)\.[^.]+$/.test(file))
+            continue;
+        const absolute = join(dir, file);
+        const code = readFileSync(absolute, 'utf8');
+        if (!code.includes('react-router') && !code.includes('vue-router') && !code.includes('Route'))
+            continue;
+        const ast = parseFile(code, absolute);
+        if (ast)
+            parsed.push({ file: absolute, code, ast });
+    }
+    return parsed;
+}
+/** Local names this module imports from `sources` (imported name → local name). */
+function importsFrom(ast, sources) {
+    const names = new Map();
+    for (const statement of ast.program.body) {
+        if (statement.type !== 'ImportDeclaration' || !sources.includes(statement.source.value))
+            continue;
+        for (const specifier of statement.specifiers) {
+            if (specifier.type === 'ImportSpecifier')
+                names.set(specifier.imported.name ?? specifier.imported.value, specifier.local.name);
+        }
+    }
+    return names;
+}
+/** The file a component reference renders: `<Home />`, `Home`, `() => import('./Home')`, `lazy(() => import('./Home'))`. */
+function componentFile(node, module, aliases) {
+    if (!node)
+        return null;
+    const current = unwrapTs(node);
+    if (current.type === 'JSXElement') {
+        const name = jsxName(current);
+        return name ? componentFile({ type: 'Identifier', name }, module, aliases) : null;
+    }
+    if (current.type === 'Identifier') {
+        const source = importSourceOf(module.ast, current.name);
+        if (source)
+            return resolveImport(module.file, source, aliases);
+        const init = topLevelConst(module.ast, current.name);
+        return init ? componentFile(init, module, aliases) : null;
+    }
+    let imported = null;
+    walk(current, inner => {
+        if (imported === null && inner.type === 'ImportExpression' && inner.source.type === 'StringLiteral')
+            imported = inner.source.value;
+        if (imported === null && inner.type === 'CallExpression' && inner.callee.type === 'Import' && inner.arguments[0]?.type === 'StringLiteral')
+            imported = inner.arguments[0].value;
+    });
+    return imported ? resolveImport(module.file, imported, aliases) : null;
+}
+/** An array of route objects through a same-file const or an imported module's export. */
+function routeArray(node, module, aliases, depth = 0) {
+    const current = unwrapTs(node);
+    if (depth > 4)
+        throw new Unreadable('a route list init cannot follow');
+    if (current?.type === 'ArrayExpression')
+        return { list: current, module };
+    if (current?.type === 'Identifier') {
+        const init = topLevelConst(module.ast, current.name);
+        if (init)
+            return routeArray(init, module, aliases, depth + 1);
+        const source = importSourceOf(module.ast, current.name);
+        const file = source ? resolveImport(module.file, source, aliases) : null;
+        if (file) {
+            const code = readFileSync(file, 'utf8');
+            const ast = parseFile(code, file);
+            if (!ast)
+                throw new Unreadable(`${file}, which does not parse`);
+            const imported = { file, code, ast };
+            const specifier = module.ast.program.body.flatMap((statement) => (statement.type === 'ImportDeclaration' ? statement.specifiers : []))
+                .find((candidate) => candidate.local.name === current.name);
+            const exportedName = specifier?.type === 'ImportSpecifier' ? (specifier.imported.name ?? specifier.imported.value) : null;
+            if (exportedName) {
+                const init = topLevelConst(ast, exportedName);
+                if (init)
+                    return routeArray(init, imported, aliases, depth + 1);
+            }
+            else {
+                const exported = ast.program.body.find((statement) => statement.type === 'ExportDefaultDeclaration')?.declaration;
+                if (exported)
+                    return routeArray(exported, imported, aliases, depth + 1);
+            }
+        }
+    }
+    throw new Unreadable('a route list that is not an array literal');
+}
+function stringValue(node, ast, what) {
+    const value = node ? literalValue(node, ast) : UNREADABLE;
+    if (typeof value !== 'string')
+        throw new Unreadable(`a ${what} that is not a literal string`);
+    return value;
+}
+function joinPath(parent, child) {
+    if (child.startsWith('/'))
+        return child;
+    return `${parent.replace(/\/+$/, '')}/${child}`;
+}
+function properties(object) {
+    const map = new Map();
+    for (const property of object.properties) {
+        if (property.type === 'SpreadElement')
+            throw new Unreadable('a route object with a spread');
+        const name = keyName(property);
+        if (name === null)
+            throw new Unreadable('a route object with a computed key');
+        map.set(name, property.type === 'ObjectMethod' ? property : property.value);
+    }
+    return map;
+}
+/* ------------------------------------------------------------ React Router */
+/** A basename as React Router reads it ('/app/' and 'app' are '/app'); '' for none. */
+function normalBasename(value) {
+    const trimmed = value.replace(/\/+$/, '');
+    return trimmed === '' ? '' : trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+/** createBrowserRouter(routes, { basename })'s basename: '' without options; options init cannot read are Unreadable. */
+function optionsBasename(node, module) {
+    if (!node)
+        return '';
+    const options = unwrapTs(node);
+    if (options?.type !== 'ObjectExpression')
+        throw new Unreadable('router options that are not an object literal (they may set a basename)');
+    const props = properties(options);
+    return props.has('basename') ? normalBasename(stringValue(props.get('basename'), module.ast, 'router basename')) : '';
+}
+/** <BrowserRouter basename="/app">'s basename. */
+function jsxBasename(element, module) {
+    if (element.openingElement.attributes.some((item) => item.type === 'JSXSpreadAttribute'))
+        throw new Unreadable('a router component with spread props');
+    const attribute = element.openingElement.attributes.find((item) => item.type === 'JSXAttribute' && item.name.name === 'basename');
+    if (!attribute)
+        return '';
+    const value = attribute.value?.type === 'JSXExpressionContainer' ? attribute.value.expression : attribute.value;
+    return normalBasename(stringValue(value, module.ast, 'router basename'));
+}
+const RR_SOURCES = ['react-router', 'react-router-dom'];
+export function reactRouterLibraryRoutes(ctx, srcDir) {
+    const aliases = readPathAliases(ctx.appDir);
+    const modules = sourceFiles(srcDir);
+    const routes = [];
+    let hashComponent = false;
+    let browserComponent = false;
+    let found = false;
+    // The router's basename prefixes every route (React Router matches below it): a router component's (one value for the
+    // app), or a data router's own option; one init cannot read is a manual step.
+    const componentBasenames = new Set();
+    let basename = '';
+    const add = (path, hash, file, module, index) => {
+        const full = basename === '' ? path : `${basename}${path.startsWith('/') ? '' : '/'}${path}`;
+        routes.push({ ...ruleFor(reactRouterSegments(full), hash), source: repoPath(ctx, file ?? module.file), rank: index ? 0 : 1 });
+    };
+    const objects = (list, module, parent, hash) => {
+        for (const element of list.elements) {
+            const route = element ? unwrapTs(element) : null;
+            if (!route || route.type !== 'ObjectExpression')
+                throw new Unreadable('a route that is not an object literal');
+            const props = properties(route);
+            const index = props.has('index') && literalValue(props.get('index'), module.ast) === true;
+            const path = props.has('path') ? joinPath(parent, stringValue(props.get('path'), module.ast, 'route path')) : parent;
+            const file = componentFile(props.get('element') ?? props.get('Component') ?? props.get('lazy'), module, aliases);
+            if ((props.has('path') || index) && (props.has('element') || props.has('Component') || props.has('lazy')))
+                add(path, hash, file, module, index);
+            if (props.has('children')) {
+                const children = routeArray(props.get('children'), module, aliases);
+                objects(children.list, children.module, path, hash);
+            }
+        }
+    };
+    const elements = (node, module, parent, hash, routeName) => {
+        for (const child of node.children ?? []) {
+            if (child.type === 'JSXText' && child.value.trim() === '')
+                continue;
+            if (child.type !== 'JSXElement' || jsxName(child) !== routeName) {
+                if (child.type === 'JSXElement' || child.type === 'JSXFragment')
+                    elements(child, module, parent, hash, routeName);
+                continue;
+            }
+            const attribute = (name) => {
+                const found = child.openingElement.attributes.find((item) => item.type === 'JSXAttribute' && item.name.name === name);
+                if (!found)
+                    return undefined;
+                return found.value === null ? { type: 'BooleanLiteral', value: true } : found.value.type === 'JSXExpressionContainer' ? found.value.expression : found.value;
+            };
+            if (child.openingElement.attributes.some((item) => item.type === 'JSXSpreadAttribute'))
+                throw new Unreadable('a <Route> with spread props');
+            const index = attribute('index') !== undefined && literalValue(attribute('index'), module.ast) === true;
+            const pathNode = attribute('path');
+            const path = pathNode ? joinPath(parent, stringValue(pathNode, module.ast, '<Route> path')) : parent;
+            const target = attribute('element') ?? attribute('Component') ?? attribute('component') ?? attribute('lazy');
+            if ((pathNode || index) && target)
+                add(path, hash, componentFile(target, module, aliases), module, index);
+            elements(child, module, path, hash, routeName);
+        }
+    };
+    try {
+        for (const module of modules) {
+            const names = importsFrom(module.ast, RR_SOURCES);
+            if (names.size === 0)
+                continue;
+            walk(module.ast.program, node => {
+                if (node.type === 'JSXElement') {
+                    const name = jsxName(node);
+                    const isHash = name !== null && name === names.get('HashRouter');
+                    const isBrowser = name !== null && name === names.get('BrowserRouter');
+                    if (isHash)
+                        hashComponent = true;
+                    if (isBrowser)
+                        browserComponent = true;
+                    if (isHash || isBrowser)
+                        componentBasenames.add(jsxBasename(node, module));
+                }
+            });
+        }
+        if (hashComponent && browserComponent)
+            return { manual: 'the app uses both BrowserRouter and HashRouter' };
+        if (componentBasenames.size > 1)
+            return { manual: `the app's router components use several basenames (${[...componentBasenames].join(', ')})` };
+        const componentBasename = [...componentBasenames][0] ?? '';
+        for (const module of modules) {
+            const names = importsFrom(module.ast, RR_SOURCES);
+            if (names.size === 0)
+                continue;
+            walk(module.ast.program, node => {
+                if (node.type === 'CallExpression' && node.callee.type === 'Identifier') {
+                    const callee = node.callee.name;
+                    const hash = callee === names.get('createHashRouter');
+                    if (callee === names.get('createBrowserRouter') || hash || callee === names.get('useRoutes')) {
+                        found = true;
+                        basename = callee === names.get('useRoutes') ? componentBasename : optionsBasename(node.arguments[1], module);
+                        const arg = unwrapTs(node.arguments[0]);
+                        if (arg?.type === 'CallExpression' && arg.callee.type === 'Identifier' && arg.callee.name === names.get('createRoutesFromElements')) {
+                            const root = unwrapTs(arg.arguments[0]);
+                            if (root?.type !== 'JSXElement' && root?.type !== 'JSXFragment')
+                                throw new Unreadable('createRoutesFromElements without JSX');
+                            elements({ children: [root] }, module, '', hash, names.get('Route') ?? 'Route');
+                        }
+                        else {
+                            const routesList = routeArray(node.arguments[0], module, aliases);
+                            objects(routesList.list, routesList.module, '', callee === names.get('useRoutes') ? hashComponent : hash);
+                        }
+                        return false;
+                    }
+                }
+                if (node.type === 'JSXElement' && names.has('Routes') && jsxName(node) === names.get('Routes')) {
+                    found = true;
+                    basename = componentBasename;
+                    elements(node, module, '', hashComponent, names.get('Route') ?? 'Route');
+                    return false;
+                }
+                return undefined;
+            });
+        }
+    }
+    catch (error) {
+        if (error instanceof Unreadable)
+            return { manual: `the React Router configuration has ${error.message}` };
+        throw error;
+    }
+    if (!found)
+        return { manual: `no React Router route definitions (createBrowserRouter, createHashRouter, useRoutes, <Routes>) were found under ${repoPath(ctx, srcDir)}` };
+    return routes;
+}
+/* ------------------------------------------------------------ Vue Router */
+/** A Vue Router path (`/users/:id?`, `/:pathMatch(.*)*`, `/docs/:slug+`) as segments. A custom regex (`:id(\\d+)`) or text
+ * mixed with a parameter constrains more than the pattern syntax can say, so such a segment is inexact (route-pattern.ts
+ * ruleFor); `(.*)` with `*` or `+` is exactly a catch-all. */
+export function vueSegments(path) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const char of path) {
+        if (char === '(')
+            depth += 1;
+        if (char === ')')
+            depth -= 1;
+        if (char === '/' && depth === 0) {
+            parts.push(current);
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    parts.push(current);
+    return parts.filter(part => part !== '').map((part) => {
+        const whole = /^:([A-Za-z0-9_]+)(\(.*\))?([?*+])?$/.exec(part);
+        if (whole) {
+            const [, name, regex, modifier] = whole;
+            const repeated = modifier === '*' || modifier === '+';
+            const constraint = regex !== undefined && !(repeated && regex === '(.*)') ? { inexact: `a parameter with a custom pattern (${part})` } : {};
+            if (modifier === '*')
+                return { kind: 'splat', name: paramName(name), optional: true, ...constraint };
+            if (modifier === '+')
+                return { kind: 'splat', name: paramName(name), optional: false, ...constraint };
+            return { kind: 'param', name: paramName(name), optional: modifier === '?', ...constraint };
+        }
+        if (part.includes(':'))
+            return { kind: 'param', name: paramName(part), optional: false, inexact: `a segment mixing text and a parameter (${part})` };
+        return { kind: 'literal', value: part };
+    });
+}
+export function vueRouterRoutes(ctx, srcDir, viteBase) {
+    const aliases = readPathAliases(ctx.appDir);
+    const routes = [];
+    let routers = 0;
+    const records = (list, module, parent, hash) => {
+        for (const element of list.elements) {
+            const record = element ? unwrapTs(element) : null;
+            if (!record || record.type !== 'ObjectExpression')
+                throw new Unreadable('a route record that is not an object literal');
+            const props = properties(record);
+            const own = stringValue(props.get('path'), module.ast, 'route path');
+            const path = own === '' ? parent : joinPath(parent === '' ? '/' : parent, own);
+            if (props.has('component') || props.has('components')) {
+                routes.push({ ...ruleFor(vueSegments(path), hash), rank: own === '' ? 0 : 1,
+                    source: repoPath(ctx, componentFile(props.get('component'), module, aliases) ?? module.file) });
+            }
+            if (props.has('children')) {
+                const children = routeArray(props.get('children'), module, aliases);
+                records(children.list, children.module, path, hash);
+            }
+        }
+    };
+    try {
+        for (const module of sourceFiles(srcDir)) {
+            const names = importsFrom(module.ast, ['vue-router']);
+            const create = names.get('createRouter');
+            if (!create)
+                continue;
+            walk(module.ast.program, node => {
+                if (node.type !== 'CallExpression' || node.callee.type !== 'Identifier' || node.callee.name !== create)
+                    return undefined;
+                routers += 1;
+                const options = unwrapTs(node.arguments[0]);
+                if (options?.type !== 'ObjectExpression')
+                    throw new Unreadable('createRouter options that are not an object literal');
+                const props = properties(options);
+                const history = unwrapTs(props.get('history'));
+                if (history?.type !== 'CallExpression' || history.callee.type !== 'Identifier')
+                    throw new Unreadable('a history init cannot read');
+                const kind = [...names.entries()].find(([, local]) => local === history.callee.name)?.[0];
+                if (kind !== 'createWebHistory' && kind !== 'createWebHashHistory')
+                    throw new Unreadable(`a history (${history.callee.name}) that is not createWebHistory or createWebHashHistory`);
+                const baseArg = history.arguments[0];
+                if (baseArg) {
+                    const isViteBase = baseArg.type === 'MemberExpression' && module.code.slice(baseArg.start, baseArg.end).replace(/\s/g, '') === 'import.meta.env.BASE_URL';
+                    const base = isViteBase ? viteBase : literalValue(baseArg, module.ast);
+                    if (base !== '/' && base !== '' && !(kind === 'createWebHashHistory'))
+                        throw new Unreadable('a history base path the manifest cannot be published under');
+                }
+                const list = routeArray(props.get('routes'), module, aliases);
+                records(list.list, list.module, '', kind === 'createWebHashHistory');
+                return false;
+            });
+        }
+    }
+    catch (error) {
+        if (error instanceof Unreadable)
+            return { manual: `the Vue Router configuration has ${error.message}` };
+        throw error;
+    }
+    if (routers !== 1)
+        return { manual: `${routers} createRouter calls were found under ${repoPath(ctx, srcDir)}, not one` };
+    return routes;
+}

package/dist/capture/adapters/django.js

@@ -0,0 +1,134 @@
+/**
+ * Django 3–6 (CAPTURE-V1 rule 8b): the tag goes into the one base template init can enumerate (the only template under a
+ * templates/ directory with a <head>), referring to the file through {% static %} (with {% load static %} added when the
+ * template lacks it), and the file goes into that Django app's static/ directory, where the staticfiles app collects
+ * it. A base template outside an app directory (a STATICFILES_DIRS entry init cannot read) is a manual step.
+ *
+ * The route manifest is a manual step for Django: its URLconf is Python only Django can evaluate, and Django serves
+ * static files under STATIC_URL, never at /.well-known/ on the origin root, so publishing needs a URL pattern or a
+ * web-server rule init does not write. Until a manifest is published the tag does nothing (rule 13a: no manifest, no
+ * work).
+ */
+import fg from 'fast-glob';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { scanHtml, withHeadTags } from '../html.js';
+import { djangoVersion, repoPath, toPosix, appFile } from '../project.js';
+import { djangoTags, STATIC_SUBDIR } from '../tag.js';
+import { isFile } from './files.js';
+const IGNORE = ['**/node_modules/**', '**/.git/**', '**/.venv/**', '**/venv/**', '**/env/**', '**/site-packages/**',
+    '**/staticfiles/**', '**/static/**', '**/build/**', '**/dist/**'];
+const MANIFEST_STEP = 'Publish the route manifest: Django\'s URLconf is Python only Django can evaluate, and the manifest must be'
+    + ' served at /.well-known/haystack-capture/current.json (and <release>.json) on each production origin, outside STATIC_URL.'
+    + ' Until it is, the tag does nothing.';
+function mentionsDjango(appDir) {
+    for (const file of ['requirements.txt', 'pyproject.toml', 'Pipfile', 'setup.py', 'setup.cfg', 'uv.lock', 'poetry.lock', 'requirements/base.txt']) {
+        const path = join(appDir, file);
+        if (existsSync(path) && /\bdjango\b/i.test(readFileSync(path, 'utf8')))
+            return true;
+    }
+    return false;
+}
+/** The template's active {% %} tags in order: those outside {# #} comments and {% comment %} … {% endcomment %} blocks
+ * (Django ignores tags inside them). */
+function activeTags(text) {
+    const tags = [];
+    let commentDepth = 0;
+    for (let at = 0; at < text.length;) {
+        if (text.startsWith('{#', at)) {
+            const close = text.indexOf('#}', at + 2);
+            at = close === -1 ? text.length : close + 2;
+            continue;
+        }
+        if (!text.startsWith('{%', at)) {
+            at += 1;
+            continue;
+        }
+        const close = text.indexOf('%}', at + 2);
+        if (close === -1)
+            break;
+        const body = text.slice(at + 2, close).trim();
+        const name = body.split(/\s+/)[0];
+        if (name === 'comment')
+            commentDepth += 1;
+        else if (name === 'endcomment')
+            commentDepth = Math.max(0, commentDepth - 1);
+        else if (commentDepth === 0)
+            tags.push({ start: at, end: close + 2, body });
+        at = close + 2;
+    }
+    return tags;
+}
+const loadsStatic = (tag) => {
+    const words = tag.body.split(/\s+/);
+    return words[0] === 'load' && words.slice(1).includes('static');
+};
+/** The template with `static` loaded by an active {% load %} before init's first tag (at `tagAt`): as it is when one is
+ * there; else with `{% load static %}` added right after a leading {% extends %}, or at the top when the template extends
+ * nothing (Django requires {% extends %} to be its first tag). Anything else is a manual step (a TemplateSyntaxError
+ * would break every page that uses the template). */
+function withStaticLoaded(text, tagAt) {
+    const tags = activeTags(text);
+    if (tags.some(tag => tag.start < tagAt && loadsStatic(tag)))
+        return text;
+    const extendsTags = tags.filter(tag => tag.body.split(/\s+/)[0] === 'extends');
+    if (extendsTags.length > 1 || (extendsTags.length === 1 && tags[0] !== extendsTags[0])) {
+        return { manual: 'its {% extends %} is not its first tag, so init cannot place {% load static %} where Django reads it' };
+    }
+    const at = extendsTags.length === 1 ? extendsTags[0].end : 0;
+    const separator = at === 0 ? '' : '\n';
+    const next = `${text.slice(0, at)}${separator}{% load static %}${at === 0 ? '\n' : ''}${text.slice(at)}`;
+    // Proven on the result: an active load of static precedes the first tag init placed.
+    const placed = next.indexOf(`{% static '${STATIC_SUBDIR}/`);
+    return activeTags(next).some(tag => tag.start < placed && loadsStatic(tag)) ? next
+        : { manual: 'init could not place {% load static %} before its tag' };
+}
+export async function detectDjango(ctx) {
+    if (!isFile(join(ctx.appDir, 'manage.py')) || !mentionsDjango(ctx.appDir))
+        return null;
+    const version = djangoVersion(ctx.appDir);
+    const blocked = [];
+    if (!version || version.major === null || version.major < 3 || version.major > 6) {
+        blocked.push(`init knows Django 3–6, and this app's version is ${version ? `${version.version} (${version.from})` : 'not pinned in a lockfile or requirements file'}`);
+    }
+    const templates = fg.sync('**/templates/**/*.html', { cwd: ctx.appDir, ignore: IGNORE, deep: 8, onlyFiles: true }).sort()
+        .filter(file => scanHtml(readFileSync(join(ctx.appDir, file), 'utf8')).heads.length > 0);
+    const base = templates.length === 1 ? templates[0] : null;
+    // <app>/templates/...: the app directory is a Python package (an app the staticfiles finder scans for static/).
+    const appRoot = base ? toPosix(base).split('/templates/')[0] : null;
+    const appIsPackage = appRoot !== null && appRoot !== toPosix(base) && appRoot !== ''
+        && isFile(join(ctx.appDir, appRoot, '__init__.py'));
+    const staticDir = appIsPackage ? posix.join(appRoot, 'static')
+        : { manual: base ? `${repoPath(ctx, join(ctx.appDir, base))} is not inside a Django app, so its static directory is a STATICFILES_DIRS entry init cannot read`
+                : `found ${templates.length} templates with a <head> under templates/ directories, not one` };
+    return {
+        id: 'django',
+        label: `Django ${version?.version ?? '(unknown version)'}`,
+        manifestAdapter: `django@${version?.version ?? 'unknown'}`,
+        blocked: blocked.length > 0 ? blocked.join('; ') : null,
+        // The routes come from the source, so whatever stops init placing the tag stops the manifest too.
+        manifestBlocked: blocked.length > 0 ? blocked.join('; ') : null,
+        fromBuild: false,
+        rewriting: null,
+        publishNote: null,
+        buildPublishDirs: () => [],
+        buildNotes: () => [],
+        looked: [appFile(ctx, '**/templates/**/*.html'), ...templates.map(file => repoPath(ctx, join(ctx.appDir, file)))],
+        staticDir,
+        async integrate(tags) {
+            if (typeof staticDir !== 'string' || !base)
+                return typeof staticDir === 'string' ? { manual: 'no base template' } : staticDir;
+            const file = join(ctx.appDir, base);
+            const edit = withHeadTags(readFileSync(file, 'utf8'), djangoTags(tags));
+            if ('manual' in edit)
+                return { manual: `${repoPath(ctx, file)}: ${edit.manual}` };
+            const loaded = withStaticLoaded(edit.content, edit.content.indexOf(`{% static '${STATIC_SUBDIR}/`));
+            return typeof loaded === 'string' ? [{ target: file, content: loaded }] : { manual: `${repoPath(ctx, file)}: ${loaded.manual}` };
+        },
+        manualTag: tags => ['In your base template, inside <head> (with {% load static %} at its top):', ...djangoTags(tags)],
+        build: { manual: MANIFEST_STEP },
+        routes: async () => ({ manual: MANIFEST_STEP }),
+        chunks: () => [],
+        publishDirs: { manual: MANIFEST_STEP },
+    };
+}

package/dist/capture/adapters/files.js

@@ -0,0 +1,77 @@
+/** Reading the app's files for adapters: source trees for file-system routes, build output for chunk ids, and the
+ * config file a framework reads. */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseFile, readConfig } from '../js-ast.js';
+/** Every file under `root`, as posix paths relative to it; skips node_modules and dot directories. */
+export function filesUnder(root) {
+    const found = [];
+    const visit = (dir, prefix) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+                    continue;
+                visit(join(dir, entry.name), `${prefix}${entry.name}/`);
+            }
+            else if (entry.isFile()) {
+                found.push(`${prefix}${entry.name}`);
+            }
+        }
+    };
+    visit(root, '');
+    return found;
+}
+export function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Chunk ids (manifest.ts): the URL path of every .js file of a build output directory served at `urlPrefix`. */
+export function chunkIds(dir, urlPrefix) {
+    if (!isDirectory(dir))
+        return [];
+    return filesUnder(dir).filter(file => file.endsWith('.js')).map(file => `${urlPrefix}${file}`);
+}
+/** The first of `names` that exists in `dir`. */
+export function firstFile(dir, names) {
+    for (const name of names)
+        if (isFile(join(dir, name)))
+            return join(dir, name);
+    return null;
+}
+/** A framework config file and its AST; a file that does not parse is read as unreadable everywhere. */
+export function configFile(dir, names) {
+    const file = firstFile(dir, names);
+    if (!file)
+        return { file: null, ast: null };
+    return { file, ast: parseFile(readFileSync(file, 'utf8'), file) };
+}
+/** A config value: absent when there is no config file. */
+export function configValue(config, path) {
+    if (!config.file)
+        return { state: 'absent' };
+    if (!config.ast)
+        return { state: 'unreadable' };
+    return readConfig(config.ast, path);
+}
+export function exists(path) {
+    return existsSync(path);
+}

package/dist/capture/adapters/index.js

@@ -0,0 +1,74 @@
+/**
+ * The framework adapters in the order they claim an app (a framework built on Vite, like React Router or SvelteKit,
+ * before Vite itself), and the one rule for which directories are deployable apps (CAPTURE-V1 rule 8a: with several,
+ * the coding agent names one with --app; init never picks), used by every telemetry part.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { appContext } from '../project.js';
+import { detectDjango } from './django.js';
+import { detectNext } from './next.js';
+import { detectNuxt } from './nuxt.js';
+import { detectRails } from './rails.js';
+import { detectReactRouter } from './react-router.js';
+import { detectSvelteKit } from './sveltekit.js';
+import { detectStaticHtml, detectVite } from './vite.js';
+const DETECTORS = [
+    detectNext, detectReactRouter, detectSvelteKit, detectNuxt, detectVite, detectRails, detectDjango,
+];
+/** The given adapter's view of this directory (what --adapter names), or null when that adapter does not recognize it. */
+export async function detectWith(ctx, id) {
+    for (const detect of [...DETECTORS, detectStaticHtml]) {
+        const detected = await detect(ctx);
+        if (detected?.id === id)
+            return detected;
+    }
+    return null;
+}
+export const ADAPTER_IDS = ['next', 'vite', 'react-router', 'remix', 'sveltekit', 'nuxt', 'rails', 'django', 'static-html'];
+/** The adapter that claims this directory, or null. A directory with no package manifest, Gemfile or manage.py and an
+ * index.html is a static site. */
+export async function detectApp(ctx) {
+    for (const detect of DETECTORS) {
+        const detected = await detect(ctx);
+        if (detected)
+            return detected;
+    }
+    return ctx.pkg === null ? detectStaticHtml(ctx) : null;
+}
+const MARKERS = ['package.json', 'Gemfile', 'manage.py'];
+function startScript(dir) {
+    const file = join(dir, 'package.json');
+    if (!existsSync(file))
+        return false;
+    try {
+        const scripts = JSON.parse(readFileSync(file, 'utf8')).scripts;
+        return typeof scripts?.start === 'string';
+    }
+    catch {
+        // A package.json that is not JSON (a fixture) is no installable package, so no app.
+        return false;
+    }
+}
+/** The repository's deployable apps, repository-relative ('.' for the root): every directory with a tracked package.json,
+ * Gemfile or manage.py (outside node_modules) that a framework adapter claims as a web app, or whose package has a start
+ * script (a Node server, for server telemetry); the root as a static site only when there is nothing else. Needs
+ * loadBabel() (adapters read framework configs). */
+export async function discoverApps(gitRoot) {
+    const listed = spawnSync('git', ['ls-files', '-z', '--', ...MARKERS.flatMap(marker => [marker, `:(glob)**/${marker}`])], { cwd: gitRoot, encoding: 'utf8' });
+    if (listed.status !== 0)
+        throw new Error(`git ls-files failed in ${gitRoot}: ${listed.stderr.trim()}`);
+    const dirs = [...new Set(listed.stdout.split('\0').filter(path => path !== '' && !path.split('/').includes('node_modules'))
+            .map(path => posix.dirname(path)))].sort();
+    const apps = [];
+    for (const dir of dirs) {
+        const appDir = join(gitRoot, dir);
+        const detected = await detectApp(appContext(gitRoot, appDir));
+        if ((detected !== null && detected.id !== 'static-html') || startScript(appDir))
+            apps.push(dir);
+    }
+    if (apps.length === 0 && (await detectApp(appContext(gitRoot, gitRoot)))?.id === 'static-html')
+        apps.push('.');
+    return apps;
+}