@o-a/cms-agent 0.5.2 → 0.5.3

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

@@ -135,6 +135,9 @@ export function scaffoldSite(targetDir) {
             // 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',
         },
         dependencies: {
             // Pinned exact, never a ^range - at v0.x even a minor bump

package/dist/create-site/template/AGENTS.md

@@ -430,6 +430,7 @@ From `vhost/`:
 npm start          # boots the site on the port set in vhost/site.config.json
 npm run tunnel      # same, plus a public tunnel URL for sharing a preview
 npm run dev         # same, plus auto-restart whenever a theme/ file changes - use this one while iterating
+npm run stop        # stops a site started by any of the above, from any terminal
 ```
 
 `npm run dev` only watches `theme/` - content changes (via the API) already show up on the next request with no restart needed, so there's nothing to gain watching `content/` too.

package/dist/search/query-index.d.ts

@@ -0,0 +1,5 @@
+export interface SearchResult {
+    url: string;
+    title: string;
+}
+export declare function queryIndex(searchIndexPath: string, term: string): SearchResult[];

package/dist/search/query-index.js

@@ -0,0 +1,21 @@
+import { openNodeSqliteDriver } from "./drivers/node-sqlite-driver.js";
+// Never queued: an in-flight query holding an open handle during a
+// concurrent rebuild's unlink just keeps reading the pre-rebuild inode
+// (stale but consistent, never torn) - queuing a read against the same
+// queue as writes would only add latency for no correctness benefit.
+export function queryIndex(searchIndexPath, term) {
+    const driver = openNodeSqliteDriver(searchIndexPath);
+    try {
+        const rows = driver.prepare('SELECT url, title FROM pages_fts WHERE pages_fts MATCH ?').all(term);
+        // node:sqlite returns rows as [Object: null prototype] instances;
+        // rebuilt here as plain objects so callers (and assert.deepEqual)
+        // never have to know that's a driver implementation detail.
+        return rows.map((row) => {
+            const { url, title } = row;
+            return { url, title };
+        });
+    }
+    finally {
+        driver.close();
+    }
+}

package/dist/server.js

@@ -13,6 +13,7 @@ import { CHECKPOINT_AUTHOR, runCheckpoint } from "./services/checkpoint.js";
 import { startDevTunnel } from "./services/dev-tunnel.js";
 import { startIntervalJob } from "./services/interval-job.js";
 import { reindexOnBootIfMissing } from "./services/reindex-on-write.js";
+import { isProcessAlive, readPidFile, removeOwnPidFile, writePidFile } from "./services/pid-file.js";
 // Never wrap v1Routes (or any route-group plugin it registers) with
 // fastify-plugin (fp()): plain app.register() gives each file its own
 // encapsulation scope by default, which Group B's auth preHandler
@@ -165,6 +166,7 @@ export async function startServer(siteRoot, options = {}) {
         scheduler.stop();
         process.removeListener('SIGTERM', shutdown);
         process.removeListener('SIGINT', shutdown);
+        removeOwnPidFile(booted.config);
         try {
             await doCheckpoint();
         }
@@ -185,6 +187,14 @@ export async function startServer(siteRoot, options = {}) {
         // them the two real ways to pick a different one instead of
         // rethrowing Node's own stack trace.
         if (error instanceof Error && 'code' in error && error.code === 'EADDRINUSE') {
+            // Most often it's this same site, started earlier in another
+            // terminal - say so, and how to stop it from this one.
+            const running = readPidFile(booted.config);
+            if (running && running.port === serverConfig.port && running.pid !== process.pid && isProcessAlive(running.pid)) {
+                console.error(`This site is already running on port ${serverConfig.port} (process ${running.pid}).`);
+                console.error('Stop it with "npm run stop" from vhost/, then start it again.');
+                process.exit(1);
+            }
             console.error(`Port ${serverConfig.port} is already in use.`);
             console.error(`Set a different port with the PORT environment variable (e.g. PORT=3001 node server.js), or "port" in vhost/site.config.json.`);
             process.exit(1);
@@ -200,6 +210,9 @@ export async function startServer(siteRoot, options = {}) {
     const address = app.server.address();
     if (address !== null && typeof address !== 'string') {
         console.log(`Site running at http://127.0.0.1:${address.port}`);
+        // Recorded only once the port is really bound, so a start that
+        // fails never leaves a record of a site that isn't running.
+        writePidFile(booted.config, address.port);
     }
     // A search index is never git-tracked (constraint 3), so a fresh
     // clone or first-ever boot has no index file - without this,

package/dist/services/pid-file.d.ts

@@ -0,0 +1,13 @@
+import type { SiteConfig } from '../config.ts';
+export interface PidRecord {
+    pid: number;
+    serverPid: number;
+    port: number;
+    startedAt: string;
+}
+export declare function pidFilePath(config: SiteConfig): string;
+export declare function writePidFile(config: SiteConfig, port: number): void;
+export declare function readPidFile(config: SiteConfig): PidRecord | null;
+export declare function removeOwnPidFile(config: SiteConfig): void;
+export declare function removePidFile(config: SiteConfig): void;
+export declare function isProcessAlive(pid: number): boolean;

package/dist/services/pid-file.js

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function pidFilePath(config) {
+    return join(config.dataRoot, 'server.pid');
+}
+// Node sets WATCH_REPORT_DEPENDENCIES in the child it runs under
+// --watch, whose parent is then the watcher itself.
+function stopTarget() {
+    return process.env.WATCH_REPORT_DEPENDENCIES ? process.ppid : process.pid;
+}
+export function writePidFile(config, port) {
+    const record = { pid: stopTarget(), serverPid: process.pid, port, startedAt: new Date().toISOString() };
+    mkdirSync(config.dataRoot, { recursive: true });
+    writeFileSync(pidFilePath(config), `${JSON.stringify(record, null, 2)}\n`);
+}
+export function readPidFile(config) {
+    try {
+        const parsed = JSON.parse(readFileSync(pidFilePath(config), 'utf-8'));
+        const { pid, serverPid, port, startedAt } = parsed;
+        if (typeof pid !== 'number' ||
+            typeof serverPid !== 'number' ||
+            typeof port !== 'number' ||
+            typeof startedAt !== 'string') {
+            return null;
+        }
+        return { pid, serverPid, port, startedAt };
+    }
+    catch {
+        return null;
+    }
+}
+// Only removes the file if it is still this process's own record: under
+// `npm run dev` the watcher starts a new process on a theme change, and
+// the old one shutting down must not delete the record the new one has
+// just written.
+export function removeOwnPidFile(config) {
+    if (readPidFile(config)?.serverPid === process.pid) {
+        removePidFile(config);
+    }
+}
+export function removePidFile(config) {
+    rmSync(pidFilePath(config), { force: true });
+}
+// Whether a process with this id exists. EPERM means it does, but
+// belongs to another user.
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && 'code' in error && error.code === 'EPERM';
+    }
+}

package/dist/services/post-urls.d.ts

@@ -0,0 +1,3 @@
+export declare function isBlogUrl(url: string): boolean;
+export declare function urlToPostPath(url: string): string | null;
+export declare function postPathToUrl(relativePostPath: string): string;

package/dist/services/post-urls.js

@@ -0,0 +1,27 @@
+// Pure, filesystem-free mapping between a /blog/<slug> URL and a
+// post's path relative to postsRoot. Unlike pages' arbitrary nested
+// paths (about.json beside a sibling about/ directory), posts are
+// flat only - a URL with more than one segment after /blog/ is never
+// a valid post URL, enforced here rather than left to sanitisePath.
+const BLOG_PREFIX = '/blog/';
+// /blog is a permanently reserved namespace: both "/blog" itself (no
+// slug) and every "/blog/..." URL are recognised here, so a caller can
+// route the whole namespace to post resolution before ever checking
+// for a page, matching the confirmed reserved-namespace decision.
+export function isBlogUrl(url) {
+    return url === '/blog' || url.startsWith(BLOG_PREFIX);
+}
+export function urlToPostPath(url) {
+    if (!url.startsWith(BLOG_PREFIX)) {
+        return null;
+    }
+    const slug = url.slice(BLOG_PREFIX.length);
+    if (slug === '' || slug.includes('/')) {
+        return null;
+    }
+    return `${slug}.json`;
+}
+export function postPathToUrl(relativePostPath) {
+    const withoutExtension = relativePostPath.replace(/\.json$/, '');
+    return `${BLOG_PREFIX}${withoutExtension}`;
+}

package/dist/services/resolve-blog-url.d.ts

@@ -0,0 +1,11 @@
+import type { SiteConfig } from '../config.ts';
+export type ResolvedBlogUrl = {
+    kind: 'post';
+    relativePath: string;
+} | {
+    kind: 'redirect';
+    to: string;
+} | {
+    kind: 'not-found';
+};
+export declare function resolveBlogUrl(config: SiteConfig, url: string): ResolvedBlogUrl;

package/dist/services/resolve-blog-url.js

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import { sanitisePath } from "./path-safety.js";
+import { buildRedirectLookup, loadRedirects } from "./redirects.js";
+import { urlToPostPath } from "./post-urls.js";
+// Mirrors resolve-url.ts's shape exactly (a live post always wins over
+// a redirect at the same URL), kept as its own distinct result type
+// rather than reusing ResolvedUrl - clearer branching at the call site
+// and avoids touching Group C's already-tested resolve-url.ts.
+//
+// Unlike pagesRoot (always expected to exist on a real site),
+// postsRoot is optional - a site that has never used blog posts has
+// no content/posts/ directory at all. sanitisePath calls realpathSync
+// directly on its root argument, which throws a raw, uncaught ENOENT
+// if that root itself is missing - so postsRoot's existence is checked
+// first, before ever calling sanitisePath, rather than letting a
+// perfectly ordinary "no posts yet" site crash on its first /blog/ hit.
+export function resolveBlogUrl(config, url) {
+    const relativePath = urlToPostPath(url);
+    if (relativePath !== null && existsSync(config.postsRoot)) {
+        const postFile = sanitisePath(config.postsRoot, relativePath);
+        if (existsSync(postFile)) {
+            return { kind: 'post', relativePath };
+        }
+    }
+    const lookup = buildRedirectLookup(loadRedirects(config).entries);
+    const to = lookup.get(url);
+    if (to !== undefined) {
+        return { kind: 'redirect', to };
+    }
+    return { kind: 'not-found' };
+}

package/dist/stop-site/cli.d.ts

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

package/dist/stop-site/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { loadSiteConfig } from "../config.js";
+import { stopSite } from "./stop-site.js";
+// Run from vhost/ (the scaffold's own "stop" script), so the site root
+// is one level up - the same relationship check-site relies on.
+const config = loadSiteConfig(resolve(process.cwd(), '..'));
+const result = await stopSite(config);
+switch (result.outcome) {
+    case 'not-running':
+        console.log("The site isn't running.");
+        break;
+    case 'removed-stale':
+        console.log(`The site isn't running. Removed a leftover record of process ${result.pid}, which has already ended.`);
+        break;
+    case 'not-a-site':
+        console.error(`Process ${result.pid} is recorded as this site, but no site is answering on port ${result.port}, so nothing was stopped.`);
+        console.error('If you are sure the site is not running, delete vhost/data/server.pid.');
+        process.exit(1);
+        break;
+    case 'stopped':
+        console.log(`Stopped the site (was on port ${result.port}).`);
+        break;
+    case 'still-stopping':
+        console.error(`Asked the site to stop (process ${result.pid}), but it is still shutting down.`);
+        process.exit(1);
+        break;
+}

package/dist/stop-site/stop-site.d.ts

@@ -0,0 +1,26 @@
+import type { SiteConfig } from '../config.ts';
+export type StopSiteResult = {
+    outcome: 'not-running';
+} | {
+    outcome: 'removed-stale';
+    pid: number;
+} | {
+    outcome: 'not-a-site';
+    pid: number;
+    port: number;
+} | {
+    outcome: 'stopped';
+    port: number;
+} | {
+    outcome: 'still-stopping';
+    pid: number;
+};
+export interface StopSiteDeps {
+    isAlive: (pid: number) => boolean;
+    signal: (pid: number) => void;
+    isSiteListening: (port: number) => Promise<boolean>;
+    sleep: (ms: number) => Promise<void>;
+    timeoutMs: number;
+}
+export declare const defaultStopSiteDeps: StopSiteDeps;
+export declare function stopSite(config: SiteConfig, deps?: StopSiteDeps): Promise<StopSiteResult>;

package/dist/stop-site/stop-site.js

@@ -0,0 +1,56 @@
+import { isProcessAlive, readPidFile, removePidFile } from "../services/pid-file.js";
+// GET /v1/capabilities is unauthenticated and always answers with the
+// agent's own version, so it's the check that something on the recorded
+// port really is a site - not just any process that happens to have
+// been given the recorded id after the site's own ended.
+async function capabilitiesAnswer(port) {
+    try {
+        const response = await fetch(new URL('/v1/capabilities', `http://127.0.0.1:${port}`), {
+            signal: AbortSignal.timeout(2_000),
+        });
+        const body = (await response.json());
+        return response.ok && typeof body.agentVersion === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+export const defaultStopSiteDeps = {
+    isAlive: isProcessAlive,
+    signal: (pid) => process.kill(pid, 'SIGTERM'),
+    isSiteListening: capabilitiesAnswer,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    // Long enough for the final draft checkpoint a graceful shutdown runs.
+    timeoutMs: 15_000,
+};
+// Stops the site recorded in vhost/data/server.pid with SIGTERM - the
+// same graceful shutdown as Ctrl+C (the server closes and runs its
+// final draft checkpoint) - then waits for it to exit. It only ever
+// signals a process that is both alive and answering as a site on the
+// recorded port, so a leftover file from a crash never gets an
+// unrelated process that has since been given the same id killed.
+export async function stopSite(config, deps = defaultStopSiteDeps) {
+    const record = readPidFile(config);
+    if (!record) {
+        return { outcome: 'not-running' };
+    }
+    if (!deps.isAlive(record.pid)) {
+        removePidFile(config);
+        return { outcome: 'removed-stale', pid: record.pid };
+    }
+    if (!(await deps.isSiteListening(record.port))) {
+        return { outcome: 'not-a-site', pid: record.pid, port: record.port };
+    }
+    deps.signal(record.pid);
+    const pollMs = 200;
+    for (let waited = 0; waited < deps.timeoutMs; waited += pollMs) {
+        if (!deps.isAlive(record.pid) && !deps.isAlive(record.serverPid)) {
+            // The server removes its own record on a graceful shutdown; this
+            // covers one that exited without getting that far.
+            removePidFile(config);
+            return { outcome: 'stopped', port: record.port };
+        }
+        await deps.sleep(pollMs);
+    }
+    return { outcome: 'still-stopping', pid: record.pid };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o-a/cms-agent",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -25,7 +25,8 @@
     "create-site": "dist/create-site/cli.js",
     "mint-token": "dist/create-site/mint-token-cli.js",
     "check-site": "dist/site-check/cli.js",
-    "seed-media": "dist/media/seed-media-cli.js"
+    "seed-media": "dist/media/seed-media-cli.js",
+    "stop-site": "dist/stop-site/cli.js"
   },
   "files": [
     "dist"