@acms-subir/core 0.2.0 → 0.3.0

package/cli/remote.mjs

@@ -0,0 +1,55 @@
+import { homedir } from 'node:os';
+import { resolve,join,basename,extname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { fail, readJson, atomicJson, inputJson } from './common.mjs';
+const configRoot=()=>process.env.ACMS_CONFIG_DIR??join(homedir(),'.config/acms');
+function siteURL(raw){let u;try{u=new URL(raw);}catch{fail('USAGE','Supply a valid site URL.');}if(u.username||u.password||u.search||u.hash||!['http:','https:'].includes(u.protocol))fail('USAGE','URL must have no credentials, query, or fragment.');if(u.protocol==='http:'&&!['localhost','127.0.0.1','[::1]'].includes(u.hostname))fail('USAGE','Use HTTPS except for a local development server.');return u.origin;}
+export async function api(url,token,path,body,method='GET',extra={}){
+  let response;try{response=await fetch(new URL(path,url),{method,headers:{Authorization:`Bearer ${token}`,...(body&&!(body instanceof Uint8Array)?{'Content-Type':'application/json'}:{}),...extra},body:body instanceof Uint8Array?body:body?JSON.stringify(body):undefined,redirect:'error',signal:AbortSignal.timeout(20000)});}catch{fail('NETWORK','Could not reach the site. No mutation was retried.');}
+  const cap=5*1024*1024;let text='';const reader=response.body?.getReader();if(reader)try{const dec=new TextDecoder();for(;;){const {done,value}=await reader.read();if(done)break;text+=dec.decode(value,{stream:true});if(text.length>cap){await reader.cancel();fail('NETWORK','Response exceeds 5 MB.');}}}finally{reader.releaseLock();}
+  let data;try{data=JSON.parse(text);}catch{fail('NETWORK','Site did not return JSON. Check its URL and deployment.');}
+  if(!response.ok)fail(response.status===409?'CONFLICT':[401,403].includes(response.status)?'AUTH':'NETWORK',data.error??`Request failed (${response.status}).`,{status:response.status});
+  return data;
+}
+export async function remoteCommand(group,command,args,flags){
+  const path=join(configRoot(),'sites.json'),profiles=await readJson(path).catch(()=>({version:1,sites:{}}));const name=flags.site??'default';
+  if(!/^[a-zA-Z0-9_-]+$/.test(name))fail('USAGE','Invalid site profile name.');
+  if(group==='site'&&command==='connect'){
+    const url=siteURL(args[0]??flags.url),tokenEnv=flags['token-env']??'ACMS_TOKEN';if(!/^[A-Z_][A-Z0-9_]*$/.test(tokenEnv))fail('USAGE','Invalid token environment variable.');
+    const token=process.env[tokenEnv];if(!token)fail('AUTH',`Set ${tokenEnv} in your environment. No token is stored in the project.`);
+    if(flags['dry-run'])return {dryRun:true,url,profile:name,tokenEnv};
+    let capabilities;try{capabilities=await api(url,token,'/api/design/capabilities');}catch(e){if(e.code!=='AUTH'&&e.details?.status!==404)throw e;capabilities=await api(url,token,'/api/agent');}
+    profiles.sites[name]={url,tokenEnv};await atomicJson(path,profiles);return {profile:name,url,scopes:capabilities.scopes??[],capabilities:capabilities.capabilities??{design:true}};
+  }
+  const profile=profiles.sites[name];if(!profile)fail('USAGE',`Unknown profile ${name}. Run site connect first.`);const token=process.env[profile.tokenEnv];if(!token)fail('AUTH',`Set ${profile.tokenEnv}.`);
+  const url=siteURL(profile.url);
+  if(group==='design'){
+    if(command==='pull'||command==='history'){const state=await api(url,token,'/api/design');if(command==='history')return {versions:state.versions,audit:state.audit};if(flags.output){if(flags['dry-run'])return {dryRun:true,output:resolve(flags.output),revision:state.revision};await atomicJson(resolve(flags.output),{revision:state.revision,patch:state.draft??state.live});return {output:resolve(flags.output),revision:state.revision};}return state;}
+    let body;
+    if(command==='push'){if(!flags.draft)fail('USAGE','Use design push --draft; publishing is separate.');const input=await inputJson(flags.file);const source=input.patch??input;const unknown=Object.keys(source).filter(k=>!['activeTheme','designOverrides','sectionPages','siteLogo','siteFavicon','siteCover','navItems','savedAt','shareEpoch','revision'].includes(k));if(unknown.length)fail('USAGE','Unknown draft fields.',unknown);const patch=Object.fromEntries(Object.entries(source).filter(([k])=>['activeTheme','designOverrides','sectionPages','siteLogo','siteFavicon','siteCover','navItems'].includes(k)));body={operation:'stage',revision:Number(flags.revision??input.revision),patch};}
+    else if(['publish','discard','share','revoke','rollback'].includes(command))body={operation:command==='rollback'?'restore':command,revision:Number(flags.revision),...(command==='rollback'?{id:args[0]}:{}),...(command==='share'?{days:Number(flags.days??7)}:{})};
+    else fail('USAGE','Unknown design command.');
+    if(!Number.isInteger(body.revision)||body.revision<0)fail('USAGE','Supply the revision from design pull.');
+    if(flags['dry-run'])return {dryRun:true,request:body};return api(url,token,'/api/design',body,'POST');
+  }
+  if(group==='content'){
+    if(command==='capabilities')return api(url,token,'/api/agent');
+    const tools={list:'list_content',get:'get_content',create:'create_draft',update:'update_content',publish:'publish_content'};
+    const tool=tools[command];if(!tool)fail('USAGE','Unknown content command.');const arguments_=flags.file?await inputJson(flags.file):command==='list'?{kind:'posts'}:await inputJson();
+    if(flags['dry-run'])return {dryRun:true,tool,arguments:arguments_};return api(url,token,'/api/agent',{tool,arguments:arguments_},'POST');
+  }
+  if(group==='media'){
+    if(command==='list')return api(url,token,'/api/design/media');
+    if(command!=='upload'||!args[0])fail('USAGE','Use media upload <image>.');const source=resolve(args[0]);
+    if(flags['dry-run'])return {dryRun:true,file:source,compression:'img-subir@latest',action:'Upload compressed image'};
+    const r=spawnSync('npx',['--yes','img-subir@latest',source,'--json'],{encoding:'utf8',timeout:120000,maxBuffer:1000000});if(r.status!==0)fail('OPTIMIZE_FAILED','Image compression failed. Upload was not attempted.');
+    let result;try{result=JSON.parse(r.stdout);}catch{fail('OPTIMIZE_FAILED','Compression returned an unexpected result.');}
+    const item=Array.isArray(result)?result[0]:result.results?.[0]??result.files?.[0]??result;
+    const output=item.output?.path??item.copiedTo??item.input?.path??source;
+    if(typeof output!=='string')fail('OPTIMIZE_FAILED','Compression did not return an output path.');
+    const bytes=await readFile(resolve(output)),mime=({'.png':'image/png','.jpg':'image/jpeg','.jpeg':'image/jpeg','.webp':'image/webp','.gif':'image/gif'})[extname(output).toLowerCase()];if(!mime)fail('USAGE','Unsupported image format.');
+    return api(url,token,'/api/design/media',bytes,'POST',{'Content-Type':mime,'X-Filename':basename(output)});
+  }
+  fail('USAGE','Unknown remote command.');
+}

package/cli/themes.mjs

@@ -0,0 +1,127 @@
+import { readdir, readFile, writeFile, mkdir, cp, lstat, rm, rename, mkdtemp } from 'node:fs/promises';
+import { resolve, join, relative, dirname, extname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import semver from 'semver';
+import * as tar from 'tar';
+import { ThemeManifest, SectionDefinition, SectionPages, Slug, sectionDefinitions, BUILTIN_SECTIONS } from '../src/theme-sdk/contract.mjs';
+import { CORE, project, fail, exists, readJson, atomicJson } from './common.mjs';
+export async function schemaData(){return {apiVersion:1,manifest:zodToJsonSchema(ThemeManifest,{$refStrategy:'none'}),sections:zodToJsonSchema(SectionDefinition,{$refStrategy:'none'}),pages:zodToJsonSchema(SectionPages,{$refStrategy:'none'})};}
+export async function listLocalThemes(p){
+  const out=new Map();for(const [origin,base] of [['builtin',join(p.core,'src/themes')],['project',join(p.cwd,'src/themes')]]){
+    for(const name of await readdir(base).catch(()=>[])){const file=join(base,name,'theme.json');if(await exists(file)){const raw=await readJson(file);out.set(name,{slug:name,name:raw.name??name,version:raw.version??'1.0.0',origin});}}
+  }return [...out.values()];
+}
+async function themeDir(p,slug){Slug.parse(slug);const local=join(p.cwd,'src/themes',slug);return await exists(join(local,'theme.json'))?local:join(p.core,'src/themes',slug);}
+export async function filesIn(root){
+  const files=[];
+  async function walk(dir){for(const ent of await readdir(dir,{withFileTypes:true})){const file=join(dir,ent.name),rel=relative(root,file).replaceAll('\\','/');
+    if(ent.isSymbolicLink())fail('UNSAFE_THEME',`Symbolic links are not allowed: ${rel}`);
+    if(ent.name.startsWith('.')||['node_modules','dist'].includes(ent.name))continue;
+    if(ent.isDirectory())await walk(file);else files.push(rel);
+  }}await walk(root);return files.sort();
+}
+function allowedFile(file){return file==='theme.json'||file==='theme.css'||file==='README.md'||/^(templates|sections)\/[a-zA-Z0-9-]+\.astro$/.test(file)||/^assets\/[a-zA-Z0-9_./-]+\.(png|jpe?g|webp|gif|svg|avif|woff2?)$/i.test(file);}
+async function validate(dir,p){
+  const manifest=ThemeManifest.parse(await readJson(join(dir,'theme.json')));
+  if(!semver.validRange(manifest.core)||!semver.satisfies(p.version,manifest.core,{includePrerelease:true}))fail('INCOMPATIBLE',`Theme requires core ${manifest.core}; installed ${p.version}.`);
+  const files=await filesIn(dir),issues=[];
+  if(!semver.valid(manifest.version))issues.push({file:'theme.json',message:'Invalid semantic version.'});
+  for(const [type,def] of Object.entries(manifest.sections)){
+    if(!BUILTIN_SECTIONS[type]&&!def.component)issues.push({file:'theme.json',message:`Custom section ${type} must declare a component.`});
+    for(const [key,f] of Object.entries(def.fields))if(f.type==='select'&&(!f.options?.length || (f.default!==undefined&&!f.options.includes(f.default))))issues.push({file:'theme.json',message:`Section ${type}.${key} needs options and a matching default.`});
+  }
+  for(const file of files){if(!allowedFile(file))issues.push({file,message:'File is outside the theme package allowlist.'});
+    const stat=await lstat(join(dir,file));if(stat.size>20*1024*1024)issues.push({file,message:'File exceeds 20 MB.'});
+    if(file.endsWith('.astro')||file.endsWith('.css')){const text=await readFile(join(dir,file),'utf8');if(/(?:from\s*|import\s*)['"]\.\.\/.*(?:lib|components)\//.test(text))issues.push({file,message:'Use public @acms-subir/core/theme exports instead of relative core internals.'});
+      for(const match of text.matchAll(/(?:from\s*|import\s*)['"](\.[^'"]+)['"]/g)){const path=resolve(dirname(join(dir,file)),match[1]);if(!path.startsWith(dir+'/'))issues.push({file,message:'Relative import escapes theme directory.'});else if(!await exists(path))issues.push({file,message:`Missing import: ${match[1]}`});}
+      for(const match of text.matchAll(/url\(\s*["']?((?:\.\/)?assets\/[^"')\s]+)/g)){if(match[1].startsWith('http'))continue;const path=resolve(dirname(join(dir,file)),match[1]);if(!await exists(path))issues.push({file,message:`Missing asset: ${match[1]}`});}
+    }
+  }
+  for(const file of [...manifest.assets,...manifest.templates.map(t=>'templates/'+t),...Object.values(manifest.sections).map(s=>s.component).filter(Boolean)])if(!files.includes(file))issues.push({file,message:'Declared file is missing.'});
+  if(issues.length)fail('THEME_CHECK_FAILED','Theme validation failed.',issues);
+  const reports=[];const {contrast}=await import('./palette.mjs');
+  for(const [name,palette] of [['light',manifest.tokens],['dark',manifest.tokens.dark]])if(palette.bg&&palette.ink){const ratio=contrast(palette.bg,palette.ink);reports.push({check:`${name} body text contrast`,ratio,needsReview:ratio===null||ratio<4.5});}
+  return {manifest,files,reports};
+}
+async function snapshot(dir){const entries={};for(const file of await filesIn(dir))entries[file]=createHash('sha256').update(await readFile(join(dir,file))).digest('hex');return entries;}
+export async function themeCommand(command,args,flags){
+  const p=await project(),slug=args[0];
+  if(command==='install')return installTheme(p,slug,flags);
+  if(!slug)fail('USAGE','Supply a theme name.');Slug.parse(slug);
+  const dir=await themeDir(p,slug),local=join(p.cwd,'src/themes',slug);
+  if(command==='create') {
+    if(await exists(local))fail('EXISTS',`Theme ${slug} already exists.`);
+    const source=flags.from??'business';const builtin=source==='business';
+    const sourceDir=builtin?null:await themeDir(p,source);
+    if(sourceDir&&!await exists(join(sourceDir,'theme.json')))fail('NOT_FOUND',`Starter ${source} was not found.`);
+    if(flags['dry-run'])return {dryRun:true,path:local,source};
+    await mkdir(local,{recursive:true});
+    if(sourceDir){await cp(sourceDir,local,{recursive:true});for(const file of await filesIn(local))if(file.endsWith('.astro')){
+      const path=join(local,file);let text=await readFile(path,'utf8');
+      text=text.replace(/from ['"](?:\.\.\/)+lib\/schema['"]/g,"from '@acms-subir/core/theme'")
+        .replace(/from ['"](?:\.\.\/)+lib\/(content|dates)['"]/g,"from '@acms-subir/core/theme'");await writeFile(path,text);
+    }}
+    else {await mkdir(join(local,'templates'));await writeFile(join(local,'theme.css'),'.acms-sections { --section-accent: var(--accent); }\n');
+      await writeFile(join(local,'templates/home.astro'),`---\nimport type { HomeProps } from '@acms-subir/core/theme';\ninterface Props extends HomeProps {}\nconst { page } = Astro.props;\n---\n<article class="page-body">{page?.bodyHtml ? <div set:html={page.bodyHtml} /> : <h1>Welcome</h1>}</article>\n`);}
+    const raw=sourceDir?await readJson(join(local,'theme.json')):{name:slug,tokens:{accent:'#3355ff'},templates:['home.astro'],sections:{statement:{name:'Statement',version:1,component:'sections/Statement.astro',variants:['default'],fields:{heading:{label:'Heading',type:'text',default:''},text:{label:'Supporting text',type:'textarea',default:''}}}}};
+    if(builtin){await mkdir(join(local,'sections'));await writeFile(join(local,'sections/Statement.astro'),`---\nimport type { SectionProps } from '@acms-subir/core/theme';\ninterface Props extends SectionProps {}\nconst { data } = Astro.props;\n---\n<div class="studio-statement"><h2>{data.heading}</h2><p>{data.text}</p></div>\n<style>.studio-statement { max-width: 48rem; margin-inline: auto; text-align: center; } p { white-space: pre-line; }</style>\n`);}
+
+    await atomicJson(join(local,'theme.json'),{...raw,name:slug,slug,version:'1.0.0',apiVersion:1,core:`>=${p.version} <1.0.0`},0o644);
+    await atomicJson(join(p.cwd,'.acms/baselines',slug+'.json'),await snapshot(local));
+    return {created:local,next:[`acms theme dev ${slug}`,`acms theme check ${slug} --build`],sections:Object.keys(sectionDefinitions(ThemeManifest.parse(raw)))};
+  }
+  if(!await exists(join(dir,'theme.json')))fail('NOT_FOUND',`Theme ${slug} was not found.`);
+  if(command==='inspect'){const {manifest,files}=await validate(dir,p);return {slug,origin:dir===local?'project':'builtin',manifest,files,sections:sectionDefinitions(manifest),overrides:'Use design pull --site <name> to inspect runtime overrides.'};}
+  if(command==='check') {
+    const result=await validate(dir,p);let built=false;
+    if(flags.build&&!flags['dry-run']){const {buildFixture}=await import('./preview.mjs');await buildFixture(p,dir,slug);built=true;}
+    return {valid:true,slug,files:result.files,contrast:result.reports,built,manualReview:['Keyboard navigation','Narrow layouts','Custom CSS selector compatibility'],hint:built?null:'Use --build for Astro compiler checks.'};
+  }
+  if(command==='dev'){if(flags['dry-run'])return {dryRun:true,action:'Create isolated preview and start Astro'};const {devFixture}=await import('./preview.mjs');return devFixture(p,dir,slug,flags);}
+  if(command==='diff'){
+    const before=flags.baseline?await snapshot(resolve(flags.baseline)):await readJson(join(p.cwd,'.acms/baselines',slug+'.json')).catch(()=>({}));const after=await snapshot(dir);
+    return {baseline:flags.baseline??'creation snapshot',added:Object.keys(after).filter(f=>!before[f]),changed:Object.keys(after).filter(f=>before[f]&&before[f]!==after[f]),removed:Object.keys(before).filter(f=>!after[f])};
+  }
+  if(command==='pack'){
+    if(flags.optimize&&!flags['dry-run']){const r=spawnSync('npx',['--yes','img-subir@latest',dir,'--rewrite-refs','--json'],{encoding:'utf8'});if(r.status!==0)fail('OPTIMIZE_FAILED','Image compression failed.');
+      const report=JSON.parse(r.stdout);
+      for(const file of (await filesIn(dir)).filter(f=>/\.(json|astro|css|md)$/.test(f))){let text=await readFile(join(dir,file),'utf8');for(const rename of report.renamed??[]){const from=relative(dir,resolve(rename.from)).replaceAll('\\','/'),to=relative(dir,resolve(rename.to)).replaceAll('\\','/');text=text.split(from).join(to);}await writeFile(join(dir,file),text);}
+    }
+    const {manifest,files}=await validate(dir,p),output=resolve(flags.output??`${slug}-${manifest.version}.tgz`);
+    if(flags['dry-run'])return {dryRun:true,output,files};
+    if(await exists(output)&&!flags.force)fail('EXISTS','Archive exists. Choose --output or use --force.');
+    await tar.c({gzip:{mtime:0},portable:true,mtime:new Date(0),cwd:dir,file:output},files);
+    return {output,sha256:createHash('sha256').update(await readFile(output)).digest('hex'),files,version:manifest.version};
+  }
+  fail('USAGE','Unknown theme command.');
+}
+async function installTheme(p,input,flags){
+  if(!input)fail('USAGE','Supply a local theme archive.');const archive=resolve(input);
+  if((await lstat(archive)).size>30*1024*1024)fail('TOO_LARGE','Archive exceeds 30 MB.');
+  const seen=new Set();let total=0,bad=[];
+  await tar.t({file:archive,onReadEntry:e=>{
+    total+=e.size;
+    if(e.type!=='File'||e.path.includes('..')||e.path.startsWith('/')||e.path.includes('\\')||!allowedFile(e.path)||seen.has(e.path))bad.push(e.path);
+    seen.add(e.path);
+    if(total>60*1024*1024||seen.size>500)bad.push('Archive limits exceeded');
+  }});
+  if(bad.length)fail('UNSAFE_ARCHIVE','Archive contains unsafe or unsupported entries.',bad);
+  const temp=await mkdtemp(join(tmpdir(),'acms-theme-'));
+  try{
+    await tar.x({file:archive,cwd:temp,strict:true,noChmod:true});const {manifest}=await validate(temp,p);
+    const slug=manifest.slug;if(!slug)fail('INVALID_MANIFEST','Packaged themes must declare a slug.');
+    const dest=join(p.cwd,'src/themes',slug),digest=createHash('sha256').update(await readFile(archive)).digest('hex');
+    if(await exists(dest)&&!flags.force)fail('EXISTS','Theme exists. Use --force to retain a backup and replace it.');
+    if(flags['dry-run'])return {dryRun:true,slug,version:manifest.version,sha256:digest,rebuildRequired:true};
+    const stage=join(p.cwd,'src/themes',`.${slug}-${process.pid}`);await mkdir(dirname(stage),{recursive:true});await cp(temp,stage,{recursive:true});
+    let backup;
+    if(await exists(dest)){backup=join(p.cwd,'.acms/theme-backups',`${slug}-${Date.now()}`);await mkdir(dirname(backup),{recursive:true});await rename(dest,backup);}
+    try{await rename(stage,dest);}catch(e){if(backup)await rename(backup,dest);throw e;}
+    const lockPath=join(p.cwd,'.acms/themes.lock.json'),lock=await readJson(lockPath).catch(()=>({version:1,themes:{}}));lock.themes[slug]={version:manifest.version,core:manifest.core,sha256:digest,backup};await atomicJson(lockPath,lock);
+    return {installed:slug,version:manifest.version,backup,rebuildRequired:true,next:'Build, deploy, then stage theme selection. Install never changes the live site.'};
+  }finally{await rm(temp,{recursive:true,force:true});}
+}

package/cli.mjs

@@ -1,370 +1,3 @@
 #!/usr/bin/env node
-// `acms` — tiny maintenance CLI installed with @acms-subir/core.
-//   acms update           check the registry, install the latest core, print what's new
-//   acms update --check   just report whether an update exists (exit 1 if behind)
-//   acms update --next    follow the canary channel (`next` dist-tag); sticky once installed
-//   acms update --latest  leave the canary channel and go back to stable
-//   acms doctor           sanity-check the project setup
-//   acms add cloudflare   retrofit Workers deployment (wrangler.jsonc, deps, D1/R2)
-//   acms add docker       retrofit self-hosting (Dockerfile, compose.yml)
-import { spawnSync } from 'node:child_process';
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
-
-const PKG = '@acms-subir/core';
-const cmd = process.argv[2];
-
-const read = (p) => { try { return readFileSync(p, 'utf8'); } catch { return ''; } };
-const installedPkgJson = () => {
-  try {
-    return createRequire(join(process.cwd(), 'package.json')).resolve(`${PKG}/package.json`);
-  } catch { return null; }
-};
-const installedVersion = () => {
-  const p = installedPkgJson();
-  try { return p ? JSON.parse(readFileSync(p, 'utf8')).version : null; } catch { return null; }
-};
-const latestVersion = async (tag = 'latest') => {
-  const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(PKG)}/${tag}`, {
-    signal: AbortSignal.timeout(10_000),
-  });
-  if (res.status === 404 && tag !== 'latest') {
-    throw Object.assign(new Error(`the '${tag}' channel has no releases yet`), { noTag: true });
-  }
-  if (!res.ok) throw new Error(`registry responded ${res.status}`);
-  return (await res.json()).version;
-};
-const splitPre = (v) => {
-  const i = v.indexOf('-');
-  return i === -1 ? [v, ''] : [v.slice(0, i), v.slice(i + 1)];
-};
-const isCanary = (v) => splitPre(v)[1] !== '';
-const semverLt = (a, b) => {
-  const [aBase, aPre] = splitPre(a), [bBase, bPre] = splitPre(b);
-  const pa = aBase.split('.').map(Number), pb = bBase.split('.').map(Number);
-  for (let i = 0; i < 3; i++) { if ((pa[i] ?? 0) < (pb[i] ?? 0)) return true; if ((pa[i] ?? 0) > (pb[i] ?? 0)) return false; }
-  // equal bases: a release outranks any of its prereleases; two prereleases
-  // compare identifier by identifier, numerically where both sides are numbers
-  if (!aPre) return false;
-  if (!bPre) return true;
-  const as = aPre.split('.'), bs = bPre.split('.');
-  for (let i = 0; i < Math.max(as.length, bs.length); i++) {
-    const x = as[i], y = bs[i];
-    if (x === undefined) return true;
-    if (y === undefined) return false;
-    const nx = /^\d+$/.test(x), ny = /^\d+$/.test(y);
-    if (nx && ny) { if (Number(x) !== Number(y)) return Number(x) < Number(y); }
-    else if (nx !== ny) return nx;
-    else if (x !== y) return x < y;
-  }
-  return false;
-};
-
-// Release notes come from the CHANGELOG that changesets writes into the
-// package itself, read after the install from the freshly unpacked copy. No
-// git-host API is involved on purpose: the repository lives on a private
-// OneDev instance, so anything API-based would need a token on every site
-// that runs this command.
-const changelogFor = (pkgJsonPath) => (pkgJsonPath ? read(join(dirname(pkgJsonPath), 'CHANGELOG.md')) : '');
-// Entries newer than `current` up to `latest`, oldest first. Changesets writes
-// one "## X.Y.Z" heading per release.
-const releaseNotes = (md, current, latest) => {
-  // split on every "## " heading, not just the version ones, so a hand-written
-  // "## Unreleased" section cannot get swallowed into the entry above it
-  const heads = [...md.matchAll(/^## +(.*)$/gm)];
-  return heads
-    .map((h, i) => ({
-      version: h[1].trim().match(/^\d+\.\d+\.\d+$/)?.[0],
-      body: md.slice(h.index + h[0].length, heads[i + 1]?.index ?? md.length).trim(),
-    }))
-    .filter((r) => r.version && semverLt(current, r.version) && !semverLt(latest, r.version))
-    .sort((a, b) => (semverLt(a.version, b.version) ? -1 : 1));
-};
-const deployTargets = () => ({
-  cloudflare: ['wrangler.jsonc', 'wrangler.json', 'wrangler.toml'].some((f) => existsSync(f)),
-  docker: ['compose.yml', 'compose.yaml', 'docker-compose.yml', 'Dockerfile'].some((f) => existsSync(f)),
-});
-
-if (cmd === 'update') {
-  const checkOnly = process.argv.includes('--check');
-  const current = installedVersion();
-  if (!current) { console.error(`✗ ${PKG} is not installed here — run this from your site's folder.`); process.exit(1); }
-  // Channel: --next opts into canary prereleases and is sticky — once a canary
-  // is installed, a plain `acms update` keeps following the next tag until
-  // --latest switches back to stable.
-  const backToStable = process.argv.includes('--latest') && isCanary(current);
-  const channel = process.argv.includes('--latest') ? 'latest'
-    : process.argv.includes('--next') || isCanary(current) ? 'next'
-    : 'latest';
-  let latest;
-  try { latest = await latestVersion(channel); } catch (e) {
-    console.error(e.noTag ? `✗ ${e.message[0].toUpperCase()}${e.message.slice(1)}.` : `✗ Could not reach the npm registry (${e.message}).`);
-    process.exit(1);
-  }
-  // Leaving the canary channel is usually a downgrade (0.1.1-next.x → 0.1.0),
-  // so "am I behind" is the wrong question there — switch unconditionally.
-  if (!backToStable && !semverLt(current, latest)) {
-    console.log(`✓ Already up to date (${current}${channel === 'next' ? ', canary channel' : ''}).`);
-    process.exit(0);
-  }
-  if (checkOnly) {
-    console.log(`Update available: ${current} → ${latest}. Run: npx acms update${channel === 'next' ? ' --next' : backToStable ? ' --latest' : ''}`);
-    process.exit(1);
-  }
-  console.log(backToStable
-    ? `Returning to the stable channel: ${PKG} ${current} → ${latest}…`
-    : `Updating ${PKG} ${current} → ${latest}${channel === 'next' ? ' (canary)' : ''}…`);
-  const res = spawnSync('npm', ['install', `${PKG}@${channel}`, '--no-audit', '--no-fund'], { stdio: 'inherit' });
-  if (res.status !== 0) process.exit(res.status ?? 1);
-  console.log(`\n✓ Updated to ${latest}.`);
-  const notes = releaseNotes(changelogFor(installedPkgJson()), current, latest);
-  if (notes.length) {
-    console.log(`\nWhat's new:`);
-    for (const r of notes) {
-      console.log(`\n  ${PKG} ${r.version}`);
-      if (r.body) console.log(r.body.split('\n').map((l) => `    ${l}`).join('\n'));
-    }
-  } else if (channel === 'next') {
-    console.log(`\nWhat's new: canary build — notes arrive with the next stable release.`);
-  } else {
-    console.log(`\nWhat's new: https://www.npmjs.com/package/${PKG}/v/${latest}`);
-  }
-  if (channel === 'next') {
-    console.log(`\nYou're on the canary channel; \`npx acms update --latest\` returns to stable.`);
-  }
-  const t = deployTargets();
-  const steps = [
-    ...(t.cloudflare ? ['  npm run deploy                       # Cloudflare Workers'] : []),
-    ...(t.docker ? ['  git push, then on your server:       docker compose up -d --build'] : []),
-  ];
-  console.log([
-    '',
-    'Deploy when ready:',
-    ...(steps.length ? steps : ['  rebuild and redeploy your host']),
-    '  (the database migrates itself on the first request — no manual steps)',
-  ].join('\n'));
-  // the registry fetch leaves a keep-alive socket in undici's pool, which can
-  // hold the event loop open for seconds after there is nothing left to do
-  process.exit(0);
-} else if (cmd === 'add') {
-  // Retrofit a deployment target onto an existing project. Both targets share
-  // one codebase — astro.config picks the adapter via DEPLOY_TARGET — so
-  // "adding" one is only config files + deps. Content moves between backends
-  // with a backup ZIP (admin → Backup, then admin → Restore on the new host).
-  const what = process.argv[3];
-  if (!existsSync('package.json')) {
-    console.error("✗ No package.json here — run this from your site's folder.");
-    process.exit(1);
-  }
-  const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
-  const slug = (pkg.name || 'my-site').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 50) || 'my-site';
-  const writeNew = (file, body) => {
-    if (existsSync(file)) { console.log(`• ${file} already exists — left untouched`); return false; }
-    writeFileSync(file, body);
-    console.log(`✓ wrote ${file}`);
-    return true;
-  };
-  const setScript = (name, value) => {
-    pkg.scripts ??= {};
-    if (pkg.scripts[name]) return;
-    pkg.scripts[name] = value;
-    console.log(`✓ added "${name}" script`);
-  };
-
-  if (what === 'cloudflare') {
-    writeNew('wrangler.jsonc', `{
-  "$schema": "node_modules/wrangler/config-schema.json",
-  "name": "${slug}",
-  "main": "./dist/_worker.js/index.js",
-  "compatibility_date": "2025-07-01",
-  "compatibility_flags": ["nodejs_compat"],
-  "assets": {
-    "binding": "ASSETS",
-    "directory": "./dist"
-  },
-  "observability": {
-    "enabled": true
-  },
-  // Scheduled publishing: flips due scheduled posts to published every 5
-  // minutes, independent of site traffic.
-  "triggers": {
-    "crons": ["*/5 * * * *"]
-  },
-  // If the id below is still zeros, create the real database with
-  //   npx wrangler d1 create ${slug}-db
-  // and paste the returned database_id here. Local dev (wrangler dev /
-  // astro dev) uses a local simulator and works with the placeholder.
-  "d1_databases": [
-    {
-      "binding": "DB",
-      "database_name": "${slug}-db",
-      "database_id": "00000000-0000-0000-0000-000000000000"
-    }
-  ],
-  // If missing, create the real bucket with:
-  //   npx wrangler r2 bucket create ${slug}-media
-  // Local dev uses a local simulator and works without creating anything.
-  "r2_buckets": [
-    {
-      "binding": "MEDIA",
-      "bucket_name": "${slug}-media"
-    }
-  ]
-}
-`);
-    setScript('preview', 'npm run build && wrangler dev');
-    setScript('deploy', 'npm run build && wrangler deploy');
-    writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
-    if (!pkg.devDependencies?.wrangler && !pkg.dependencies?.wrangler) {
-      console.log('Installing wrangler…');
-      const res = spawnSync('npm', ['install', '-D', 'wrangler', '--no-audit', '--no-fund'], { stdio: 'inherit' });
-      if (res.status !== 0) console.error('✗ npm install -D wrangler failed — install it manually.');
-    }
-    if (process.argv.includes('--provision')) {
-      console.log(`Creating D1 database ${slug}-db…`);
-      const d1 = spawnSync('npx', ['--no-install', 'wrangler', 'd1', 'create', `${slug}-db`], { encoding: 'utf8' });
-      const id = (d1.stdout || '').match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/)?.[0];
-      if (d1.status === 0 && id) {
-        writeFileSync('wrangler.jsonc', readFileSync('wrangler.jsonc', 'utf8').replace('00000000-0000-0000-0000-000000000000', id));
-        console.log(`✓ D1 created (${id})`);
-      } else {
-        console.error(`✗ D1 creation failed — create it later with: npx wrangler d1 create ${slug}-db`);
-      }
-      const r2 = spawnSync('npx', ['--no-install', 'wrangler', 'r2', 'bucket', 'create', `${slug}-media`], { encoding: 'utf8' });
-      console.log(r2.status === 0 ? '✓ R2 bucket created' : `✗ R2 creation failed — create it later with: npx wrangler r2 bucket create ${slug}-media`);
-    }
-    console.log(`
-✓ Cloudflare target ready. Next:
-  npx wrangler d1 create ${slug}-db          # unless --provision did it; paste the id into wrangler.jsonc
-  npx wrangler secret put ADMIN_PASSWORD
-  npx wrangler secret put SESSION_SECRET
-  npm run deploy
-  Moving existing content? Admin → Backup on the old host, Admin → Restore on the new one.`);
-  } else if (what === 'docker') {
-    writeNew('Dockerfile', `# Self-hosted Node target. Build/run via compose.yml, or directly:
-#   docker build -t ${slug} . && docker run -p 4321:4321 -v acms_data:/app/data ${slug}
-FROM node:22-slim AS build
-WORKDIR /app
-COPY package.json package-lock.json* *.tgz* ./
-RUN npm install --no-audit --no-fund
-# self-heal npm/cli#4828: a lockfile updated on macOS can omit the Linux
-# platform binaries (rollup, libsql) while still "installing" cleanly
-RUN node -e "require('rollup')" >/dev/null 2>&1 || \\
-    (rm -rf node_modules package-lock.json && npm install --no-audit --no-fund)
-COPY . .
-RUN DEPLOY_TARGET=node npm run build:node
-
-FROM node:22-slim
-# WORKDIR must stay stable: SQLITE_URL and the media store resolve ./data
-# against the process CWD
-WORKDIR /app
-ENV NODE_ENV=production HOST=0.0.0.0 PORT=4321
-# the standalone bundle in dist/ contains all app code; the only runtime
-# import left in node_modules is @libsql/client (dynamically imported so it
-# stays out of the Workers bundle) — installing just that keeps the image
-# ~300MB instead of ~2GB
-RUN npm install --no-save --no-audit --no-fund "@libsql/client@^0.15.0"
-COPY --from=build /app/dist ./dist
-# ./data holds the SQLite database and uploaded media — mount a volume here.
-# Only data/ needs to be writable (a chown -R of /app would copy-on-write
-# duplicate every node_modules file into a fresh layer)
-RUN mkdir -p data && chown node:node data
-USER node
-EXPOSE 4321
-CMD ["node", "./dist/server/entry.mjs"]
-`);
-    writeNew('compose.yml', `# Self-hosting on your own server. A reverse proxy you already run (Coolify,
-# Dokploy, Traefik, nginx, Caddy) terminates TLS and routes to port 4321.
-# Secrets come from .env in this directory (compose reads it automatically).
-services:
-  site:
-    build: .
-    restart: unless-stopped
-    expose:
-      - "4321"
-    # No reverse proxy? Publish the port directly instead:
-    # ports:
-    #   - "4321:4321"
-    volumes:
-      # one volume covers everything: SQLite database + uploaded media
-      - data:/app/data
-    environment:
-      - HOST=0.0.0.0
-      - PORT=4321
-      - ADMIN_PASSWORD=\${ADMIN_PASSWORD:?set ADMIN_PASSWORD in .env}
-      - SESSION_SECRET=\${SESSION_SECRET:?set SESSION_SECRET in .env}
-      - SQLITE_URL=file:./data/acms.db
-    healthcheck:
-      # also serves as the scheduled-publish heartbeat: each probe is a real
-      # request, which triggers the middleware publish sweep
-      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:4321/').then((r)=>process.exit(r.ok?0:1),()=>process.exit(1))"]
-      interval: 300s
-      start_period: 15s
-
-volumes:
-  data:
-`);
-    writeNew('.dockerignore', `node_modules
-dist
-.astro
-data
-.env
-.dev.vars
-.wrangler
-.git
-`);
-    writeNew('.env.example', `# Copy to .env and fill in real values — compose.yml reads .env automatically.
-# .env itself is gitignored; this file is the committed record of what to set.
-ADMIN_PASSWORD=change-me
-# Random secret used to sign the session cookie (openssl rand -hex 32)
-SESSION_SECRET=
-# SQLite file used by the Node target (a volume mounts /app/data in Docker)
-SQLITE_URL=file:./data/acms.db
-`);
-    setScript('build:node', 'DEPLOY_TARGET=node astro build');
-    writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
-    console.log(`
-✓ Docker target ready. Next (on your server):
-  set real ADMIN_PASSWORD / SESSION_SECRET in .env
-  docker compose up -d --build     # or point Coolify/Dokploy/Railway at the repo
-  data lives in the volume at /app/data (SQLite + media)
-  Moving existing content? Admin → Backup on the old host, Admin → Restore on the new one.`);
-  } else {
-    console.error('Usage: acms add <cloudflare|docker> [--provision]');
-    process.exit(1);
-  }
-} else if (cmd === 'doctor') {
-  let bad = 0;
-  const check = (ok, label, hint) => {
-    console.log(`${ok ? '✓' : '✗'} ${label}${ok || !hint ? '' : `\n    ↳ ${hint}`}`);
-    if (!ok) bad++;
-  };
-  const major = Number(process.versions.node.split('.')[0]);
-  check(major >= 20, `Node ${process.versions.node} (need ≥20)`, 'Upgrade Node.');
-  check(installedVersion() !== null, `${PKG} resolvable`, 'npm install');
-  const cfg = read('astro.config.mjs') + read('astro.config.ts');
-  check(/@acms-subir\/core/.test(cfg), 'astro.config uses the acms integration', "import acms from '@acms-subir/core'");
-  check(/export\s+\{\s*server\s*\}/.test(read('src/actions/index.ts')), 'src/actions/index.ts re-exports core actions', "export { server } from '@acms-subir/core/actions';");
-  const wrangler = read('wrangler.jsonc') + read('wrangler.json') + read('wrangler.toml');
-  if (wrangler) {
-    check(!wrangler.includes('00000000-0000-0000-0000-000000000000'), 'wrangler D1 database_id is real', 'npx wrangler d1 create <name>-db, then paste the id.');
-  } else {
-    console.log('• no wrangler config (Node target?) — skipping Cloudflare checks');
-  }
-  check(existsSync('.dev.vars') || existsSync('.env'), 'local secrets file (.env / .dev.vars)', 'Set ADMIN_PASSWORD and SESSION_SECRET.');
-  console.log(bad === 0 ? '\nAll good.' : `\n${bad} issue${bad > 1 ? 's' : ''} found.`);
-  process.exit(bad === 0 ? 0 : 1);
-} else {
-  console.log(`acms — maintenance CLI for @acms-subir/core
-
-Usage:
-  acms update           Update the CMS core to the latest release
-  acms update --check   Report whether an update exists (exit 1 if behind)
-  acms update --next    Follow the canary channel (prereleases); later updates stay on it
-  acms update --latest  Leave the canary channel and return to stable releases
-  acms doctor           Check this project's setup
-  acms add cloudflare   Add Workers deployment to this project (--provision creates D1 + R2)
-  acms add docker       Add Docker self-hosting to this project`);
-  process.exit(cmd ? 1 : 0);
-}
+import { main } from './cli/main.mjs';
+await main();

package/deploy/Caddyfile

@@ -0,0 +1,8 @@
+{$SITE_DOMAIN} {
+    encode zstd gzip
+    reverse_proxy site:4321 {
+        # The API uses this adapter-recognized header for client rate limits.
+        # Overwrite any untrusted value supplied by an internet client.
+        header_up X-Forwarded-For {remote_host}
+    }
+}

package/deploy/Dockerfile

@@ -0,0 +1,34 @@
+# Self-hosted Node target. Build/run via compose.yml, or directly:
+#   docker build -t acms-site . && docker run -p 4321:4321 -v acms_data:/app/data acms-site
+FROM node:22-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json* *.tgz* ./
+RUN npm install --no-audit --no-fund
+# self-heal npm/cli#4828: a lockfile updated on macOS can omit the Linux
+# platform binaries (rollup, libsql) while still "installing" cleanly. If
+# rollup's native module is missing, re-resolve everything from scratch.
+RUN node -e "require('rollup')" >/dev/null 2>&1 || \
+    (rm -rf node_modules package-lock.json && npm install --no-audit --no-fund)
+COPY . .
+RUN DEPLOY_TARGET=node npm run build:node
+
+FROM node:22-slim
+# WORKDIR must stay stable: SQLITE_URL and the media store resolve ./data
+# against the process CWD
+WORKDIR /app
+ENV NODE_ENV=production HOST=0.0.0.0 PORT=4321
+# the standalone bundle in dist/ contains all app code; the only runtime
+# import left in node_modules is @libsql/client (dynamically imported so it
+# stays out of the Workers bundle) — installing just that keeps the image
+# ~300MB instead of ~2GB (a full prod install would pull astro, react, and
+# even miniflare/workerd via @astrojs/cloudflare)
+RUN npm install --no-save --no-audit --no-fund "@libsql/client@^0.15.0"
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules/@acms-subir/core/email-runner.mjs ./email-runner.mjs
+# ./data holds the SQLite database and uploaded media — mount a volume here.
+# Only data/ needs to be writable (a chown -R of /app would copy-on-write
+# duplicate every node_modules file into a fresh layer)
+RUN mkdir -p data && chown node:node data
+USER node
+EXPOSE 4321
+CMD ["node", "./dist/server/entry.mjs"]

package/deploy/compose.https.yml

@@ -0,0 +1,21 @@
+# Optional: only use this if you do not already run a TLS reverse proxy.
+services:
+  proxy:
+    image: caddy:2-alpine
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+    environment:
+      - SITE_DOMAIN=${SITE_DOMAIN:?set your public domain in .env}
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      site:
+        condition: service_healthy
+volumes:
+  caddy_data:
+  caddy_config: