allyhub 0.4.0 → 0.5.0

package/bin/allyhub.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -26,10 +26,19 @@ function local() {
   }
 }
 
+/** A package's version, by its folder. */
+const versionOf = (dir) =>
+  JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+
 const theirs = local();
-if (theirs !== undefined)
+if (theirs !== undefined) {
+  const [mine, project] = [versionOf(own), versionOf(theirs)];
+  if (mine !== project)
+    process.stderr.write(
+      `Using this project's allyhub ${project}, not ${mine}. ALLYHUB_NO_LOCAL=1 uses ${mine}.\n`,
+    );
   await import(pathToFileURL(join(theirs, "bin", "allyhub.js")).href);
-else {
+} else {
   const { main } = await import("../dist/main.js");
   process.exitCode = await main(process.argv.slice(2));
 }

package/dist/cloud-hearing.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{callTool as s,uploadFiles as u}from"@allyhub-next/cloud";import{cloudOf as c}from"./commands/cloud.js";const t="transcribe-elevenlabs-scribe-v2";export const cloudHearing=(e,i)=>async(l,o)=>{const a=c(e),[n]=await u(a,[l],{base:i});if(!n?.ok)throw n?.error??new Error(`${l} did not upload.`);const d=await s(a,t,{audioUrl:n.url,diarize:!1,...o.lang===void 0?{}:{language:o.lang.split("-")[0]}},{outDir:i,base:i,...o.signal?{signal:o.signal}:{}});if(!("output"in d))throw new Error(`${t} did not finish.`);const r=d.output;return{model:typeof r.model=="string"?r.model:t,words:Array.isArray(r.words)?r.words:[]}};

package/dist/commands/add.js

@@ -1,6 +1,6 @@
 /*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
-import{readFile as Y}from"node:fs/promises";import{join as A,posix as B,relative as V}from"node:path";import{fileURLToPath as W}from"node:url";import{z as h}from"zod";import{modelInfo as q}from"@allyhub-next/build";import{COMPONENTS_DIR as I}from"@allyhub-next/formats";import{EXIT as f}from"@allyhub-next/protocol";import{ASSET_DEFAULTS as G,ASSET_TYPES as K,PolyHaven as X,PolyHavenError as Z,RegistryError as J,applyAdd as T,fetchBakes as Q,folderRegistry as D,planAdd as L,searchIndex as O}from"@allyhub-next/registry";import{cacheHome as ee}from"@allyhub-next/runtimes";import{CLI_VERSION as te}from"../cli-version.js";import{CommandError as j,defineCommand as C}from"../command.js";import{projectRoot as ne}from"../project.js";import{dir as oe}from"../fields.js";import{resourcesIndex as P}from"../resources.js";const _=W(new URL(".",import.meta.resolve("@allyhub-next/components/registry.json"))),se=Object.keys(K),x=["component","3d-model","scenery","skill","template","lib","@polyhaven"],ae={"allyhub:component":"component","allyhub:model":"3d-model","allyhub:scenery":"scenery","allyhub:skill":"skill","allyhub:template":"template","allyhub:lib":"lib"},H=e=>ae[e]??e.replace(/^allyhub:/u,""),E=e=>`${H(e.type)}/${e.name}`;function ie(e){const n=/^(@?[a-z0-9-]+)\/(.+)$/u.exec(e),a=x.find(d=>d===n?.[1]);if(a===void 0||n?.[2]===void 0)throw new j("usage",n===null?`Name what to add as <type>/<name>: ${e} has no type.`:`${n[1]??""} is not a type: name what to add as <type>/<name>.`,{exit:f.usage,hint:`Types: ${x.join(", ")} (3d-model/monitor, scenery/home-desk-demo-day, skill/product-demos, component/caption-line, @polyhaven/<id>). allyhub add lists every one.`});return{type:a,name:n[2]}}const le={"allyhub:model":"3D models","allyhub:scenery":"3D sceneries","allyhub:skill":"Skills","allyhub:template":"Templates","allyhub:component":"Components","allyhub:lib":"Libs (added with what uses them)"};function F(e,n){if(e.from==="none")return["AllyHub's resources (models, sceneries) could not be read: check the connection."];const a=n??e.index?.items??[],d=Math.max(0,...a.map(o=>E(o).length)),r=[`AllyHub's resources (allyhub add <type>/<name> copies one with what it needs, its Poly Haven assets and its baked light)${e.from==="stale"?", as last read (the registry cannot be read now)":""}:`];for(const[o,p]of Object.entries(le)){const c=a.filter(u=>u.type===o);c.length!==0&&r.push(`  ${p}:`,...c.map(u=>`    ${E(u).padEnd(d)}  ${u.description}`))}return r}const N=20,z=e=>e.replace(/\.(?:ts|js)$/u,"").replaceAll(/[A-Z]/gu,n=>`-${n.toLowerCase()}`).replace(/^-/u,"");function M(e){return e instanceof J?new j(e.code,e.message,{exit:e.code==="conflict"?f.conflict:e.code==="no-item"?f.notFound:f.failed,...e.hint===void 0?{}:{hint:e.hint}}):e instanceof Z?new j(e.code,e.message,{exit:e.code==="network"?f.platform:e.code==="not-found"?f.notFound:e.code==="bad-choice"?f.usage:f.failed,...e.hint===void 0?{}:{hint:e.hint}}):e}const R=e=>new X({userAgent:`AllyHub/${te} (+https://allyhub.com)`,cacheDir:A(ee(e.env),"polyhaven"),...e.env.ALLYHUB_POLYHAVEN_API?{api:e.env.ALLYHUB_POLYHAVEN_API}:{}}),k=e=>`${e.toFixed(3)} m`;function de(e){const n=[e.type,e.category,e.size?`${k(e.size.width)} wide, ${k(e.size.depth)} deep, ${k(e.size.height)} tall`:void 0,e.covers?`one tile covers ${e.covers.map(k).join(" × ")}`:void 0,e.polycount!==void 0?`${e.polycount.toLocaleString("en")} polygons`:void 0,e.maxResolution?`up to ${String(e.maxResolution[0])} px`:void 0,e.authors.length>0?`by ${e.authors.join(", ")}`:void 0].filter(a=>a!==void 0);return`  @polyhaven/${e.id}: ${e.name} (${n.join("; ")})
-    found in ${e.matchedIn.join(", ")||"everything"}; tags ${e.tags.join(", ")}`}async function U(e,n){const a=[`${n.name} from Poly Haven (CC0, by ${n.source.authors.join(", ")||"its authors"}): ${String(n.files.length)} files in ${n.dir}/, ${n.fetched>0?`${String(n.fetched)} fetched`:"all already there"}. Records: ${n.records.join(", ")}.`];if(n.type==="model"){const r=n.main[0]??"",o=await q(e,r,await Y(A(e,r))),p=o.bounds;return a.push(p?`Measured: ${p.size.map(c=>c.toFixed(3)).join(" × ")} m along x, y (up), z; from ${p.min.map(c=>c.toFixed(3)).join(", ")} to ${p.max.map(c=>c.toFixed(3)).join(", ")}.`:`Not measured: ${o.contentsMissing??"no contents"}.`,...o.missing.length>0?[`Missing: ${o.missing.join(", ")}.`]:[],`In a scenery: const m = await w.load("${r}");`),{lines:a,model:o}}if(n.type==="hdri")return a.push(`In a scenery: await w.environment("${n.main[0]??""}", { background: true });`),{lines:a};const d=n.covers;return a.push(d&&d.length>=2?`One tile covers ${k(d[0]??0)} × ${k(d[1]??0)} (Poly Haven's dimensions): a surface's repeat is its size over that.`:"Poly Haven gives no size for one tile.",...n.main.map((r,o)=>{const p=n.maps?.[o]??"";return`  ${p}: await w.texture("${r}"${p==="diffuse"?"":', { colorSpace: "linear" }'})`})),{lines:a}}export const add=C({name:"add",summary:"Adds to the project what AllyHub and Poly Haven have, each named <type>/<name>: a starter component, a 3D model, a 3D scenery, a skill or a template from AllyHub's registry, or a CC0 model, HDRI or texture from Poly Haven; alone it lists everything AllyHub has, by type",input:h.strictObject({name:h.array(h.string()).optional().describe("What to add, each <type>/<name>: component/caption-line, 3d-model/monitor, scenery/home-desk-demo-day, skill/product-demos (a skill goes in .agents/skills, linked from .claude/skills), template/<name>, lib/<name>, or @polyhaven/<id> (as allyhub add search prints it)"),to:h.string().optional().describe(`The folder the files go in, from the project (default ${I} for a component; for an asset, its kind's folder under assets/media/ and its id)`),force:h.boolean().default(!1).describe("Replace a component's copy the project changed (its changes are lost)"),res:h.string().optional().describe(`An asset's resolution, of its textures or of the HDRI (default ${G.resolution})`),dir:oe}),positional:["name"],output:h.looseObject({}),examples:["allyhub add","allyhub add component/caption-line","allyhub add 3d-model/monitor scenery/home-desk-demo-day","allyhub add @polyhaven/metal_office_desk --res 2k"]},async(e,n)=>{const a=D(_);try{const d=await a.index();if(!e.name||e.name.length===0){const t=Math.max(...d.items.map(y=>`component/${y.name}`.length)),l=await P(n);return{value:{components:d.items,resources:l.index?.items??[]},text:["Starter components (allyhub add component/<name> copies one into components/; allyhub add search <words> finds among everything, Poly Haven's models, HDRIs and textures too):",...d.items.map(y=>`  ${`component/${y.name}`.padEnd(t)}  ${y.description}`),"",...F(l,void 0)].join(`
-`)}}const r=e.name.map(ie),o=await ne(n.cwd,e.dir),p=new Set(d.items.map(t=>t.name)),c=t=>t.type==="component"&&p.has(z(t.name)),u=r.filter(c).map(t=>z(t.name)),v=r.filter(t=>t.type==="@polyhaven").map(t=>t.name),g=r.filter(t=>t.type!=="@polyhaven"&&!c(t)),b=g.length>0?await P(n):void 0;for(const t of g){const l=b?.index?.items.find(y=>y.name===t.name);if(!l)throw new j("no-item",`There is no ${t.type}/${t.name}.`,{exit:f.notFound,hint:b?.from==="none"?"AllyHub's registry could not be read: check the connection.":`allyhub add search --type ${t.type} lists them.`});if(H(l.type)!==t.type)throw new j("usage",`${t.name} is a ${H(l.type)}, not a ${t.type}.`,{exit:f.usage,hint:`allyhub add ${E(l)}`})}const w=g.map(t=>t.name),i=[],S={};if(u.length>0){const t=e.to??I,l=await L(a,u,{root:o,dir:t,force:e.force});await T(o,l);const y=m=>m==="up to date"?"Up to date":m==="added"?"Added":"Replaced";i.push(...l.files.map(m=>`${y(m.status)} ${m.path}`));const s=l.items.find(m=>m.name===u[0]),$=s?.files[0]?.target.replaceAll("{dir}",t);if(s&&$){const m=V(A(o,"name"),A(o,$)).split("\\").join("/").replace(/\.ts$/u,".js");i.push(`Import it from an item's entry file (<name>/video.ts): import { ${s.title} } from "${m.startsWith(".")?m:`./${m}`}"; one "../" more for each folder the item is deeper.`,"The file is the project's: change it as you like. allyhub add component/<name> --force puts the registry's back.")}l.missing.length>0&&i.push(`It needs packages the project does not declare: ${l.missing.join(", ")}.`),S.components=l.files.map(m=>({item:m.item,path:m.path,status:m.status})),S.missing=l.missing}if(b&&w.length>0){const t=await L(b.source,w,{root:o,dir:".",force:e.force});await T(o,t),i.length>0&&i.push(""),i.push(...t.files.map(s=>`${s.status==="up to date"?"Up to date":s.status==="added"?"Added":"Replaced"} ${s.path}`));const l=R(n);for(const s of t.assets){const $=await l.add(s.id,{root:o,...s.resolution===void 0?{}:{resolution:s.resolution},...s.maps===void 0?{}:{maps:s.maps}});i.push(...(await U(o,$)).lines)}const y=await Q(o,t.bakes);i.push(...y.map(s=>`${s.status==="added"?"Downloaded":"Up to date"} the baked light for ${s.bake.scenery}: ${s.path}`),"The files are the project's: change them as you like (a changed scenery is drawn unbaked until allyhub scenery bake bakes it again). allyhub add <type>/<name> --force puts the registry's back."),S.resources={files:t.files.map(s=>({item:s.item,path:s.path,status:s.status})),assets:t.assets,bakes:y.map(s=>({path:s.path,status:s.status}))}}if(v.length>0){const t=R(n),l=[];for(const y of v){const s=await t.add(y,{root:o,...e.to===void 0||u.length>0?{}:{to:B.normalize(e.to)},...e.res===void 0?{}:{resolution:e.res}}),$=await U(o,s);i.length>0&&i.push(""),i.push(...$.lines),l.push({...s,...$.model===void 0?{}:{model:$.model}})}S.assets=l}return{value:S,text:i.join(`
-`)}}catch(d){throw M(d)}}),addSearch=C({name:"add search",summary:"Finds the starter components, AllyHub's resources (models, sceneries) and Poly Haven's CC0 models, HDRIs and textures whose names, tags, categories or descriptions hold every word, each with where its words were found; with no words, lists every one",input:h.strictObject({words:h.array(h.string()).default([]).describe("The words to find (a word may start one of theirs); none lists every one"),type:h.array(h.enum(x)).optional().describe(`Only these types (default all): ${x.join(", ")} (@polyhaven: Poly Haven's models, HDRIs and textures)`),all:h.boolean().default(!1).describe(`Every match, not only the first ${String(N)} Poly Haven assets`)}),positional:["words"],output:h.looseObject({}),examples:["allyhub add search --type 3d-model",'allyhub add search "office desk" --type @polyhaven',"allyhub add search caption --type component"]},async(e,n)=>{const a=e.words.join(" ").trim(),d=a===""?"":` hold "${a}"`;try{const r=e.type??x,o=r.includes("component")?O(await D(_).index(),a):[],p=r.filter(i=>i!=="@polyhaven"),c=p.length>0?await P(n):void 0,u=c?.index?O(c.index,a).filter(i=>p.includes(H(i.type))):[],v=r.includes("@polyhaven")?se:[],{found:g,total:b}=v.length>0?await R(n).search(a,v):{found:[],total:0},w=e.all?g:g.slice(0,N);return{value:{query:a,components:o,resources:u,assets:{total:b,matches:g.length,found:w}},text:[...r.includes("component")?[`Starter components: ${String(o.length)}${d}.`,...o.map(i=>`  component/${i.name} (${i.title}): ${i.description}`)]:[],...c?c.from==="none"?F(c,[]):[`AllyHub's resources: ${String(u.length)}${d}${c.from==="stale"?" (as last read)":""}.`,...u.map(i=>`  ${E(i)} (${i.title}): ${i.description}`)]:[],...v.length>0?[`From Poly Haven (CC0): ${String(g.length)} of ${String(b)} assets${d}${w.length<g.length?`; the first ${String(w.length)} (--all for every one)`:""}.`,...w.map(de)]:[],"","Add one: allyhub add <type>/<name>"].join(`
+import{readFile as Y}from"node:fs/promises";import{join as A,posix as B,relative as V}from"node:path";import{fileURLToPath as W}from"node:url";import{z as p}from"zod";import{modelInfo as q}from"@allyhub-next/build";import{COMPONENTS_DIR as I}from"@allyhub-next/formats";import{EXIT as f}from"@allyhub-next/protocol";import{ASSET_DEFAULTS as G,ASSET_TYPES as K,PolyHaven as X,PolyHavenError as Z,RegistryError as J,applyAdd as T,fetchBakes as Q,folderRegistry as D,planAdd as L,searchIndex as O}from"@allyhub-next/registry";import{cacheHome as ee}from"@allyhub-next/runtimes";import{CLI_VERSION as te}from"../cli-version.js";import{CommandError as S,defineCommand as C}from"../command.js";import{projectRoot as ne}from"../project.js";import{dir as oe}from"../fields.js";import{resourcesIndex as R}from"../resources.js";const _=W(new URL(".",import.meta.resolve("@allyhub-next/components/registry.json"))),se=Object.keys(K),x=["component","3d-model","scenery","skill","template","lib","@polyhaven"],ae={"allyhub:component":"component","allyhub:model":"3d-model","allyhub:scenery":"scenery","allyhub:skill":"skill","allyhub:template":"template","allyhub:lib":"lib"},H=e=>ae[e]??e.replace(/^allyhub:/u,""),E=e=>`${H(e.type)}/${e.name}`;function ie(e){const n=/^(@?[a-z0-9-]+)\/(.+)$/u.exec(e),i=x.find(d=>d===n?.[1]);if(i===void 0||n?.[2]===void 0)throw new S("usage",n===null?`Name what to add as <type>/<name>: ${e} has no type.`:`${n[1]??""} is not a type: name what to add as <type>/<name>.`,{exit:f.usage,hint:`Types: ${x.join(", ")} (3d-model/monitor, scenery/home-desk-demo-day, skill/product-demos, component/caption-line, @polyhaven/<id>). allyhub add lists every one.`});return{type:i,name:n[2]}}const le={"allyhub:model":"3D models","allyhub:scenery":"3D sceneries","allyhub:skill":"Skills","allyhub:template":"Templates","allyhub:component":"Components","allyhub:lib":"Libs (added with what uses them)"};function F(e,n){if(e.from==="none")return["AllyHub's resources (models, sceneries) could not be read: check the connection."];const i=n??e.index?.items??[],d=Math.max(0,...i.map(s=>E(s).length)),r=[`AllyHub's resources (allyhub add <type>/<name> copies one with what it needs, its Poly Haven assets and its baked light)${e.from==="stale"?", as last read (the registry cannot be read now)":""}:`];for(const[s,h]of Object.entries(le)){const c=i.filter(u=>u.type===s);c.length!==0&&r.push(`  ${h}:`,...c.map(u=>`    ${E(u).padEnd(d)}  ${u.description}`))}return r}const N=20,z=e=>e.replace(/\.(?:ts|js)$/u,"").replaceAll(/[A-Z]/gu,n=>`-${n.toLowerCase()}`).replace(/^-/u,"");function M(e){return e instanceof J?new S(e.code,e.message,{exit:e.code==="conflict"?f.conflict:e.code==="no-item"?f.notFound:f.failed,...e.hint===void 0?{}:{hint:e.hint}}):e instanceof Z?new S(e.code,e.message,{exit:e.code==="network"?f.platform:e.code==="not-found"?f.notFound:e.code==="bad-choice"?f.usage:f.failed,...e.hint===void 0?{}:{hint:e.hint}}):e}const P=e=>new X({userAgent:`AllyHub/${te} (+https://allyhub.com)`,cacheDir:A(ee(e.env),"polyhaven"),...e.env.ALLYHUB_POLYHAVEN_API?{api:e.env.ALLYHUB_POLYHAVEN_API}:{}}),k=e=>`${e.toFixed(3)} m`;function de(e){const n=[e.type,e.category,e.size?`${k(e.size.width)} wide, ${k(e.size.depth)} deep, ${k(e.size.height)} tall`:void 0,e.covers?`one tile covers ${e.covers.map(k).join(" × ")}`:void 0,e.polycount!==void 0?`${e.polycount.toLocaleString("en")} polygons`:void 0,e.maxResolution?`up to ${String(e.maxResolution[0])} px`:void 0,e.authors.length>0?`by ${e.authors.join(", ")}`:void 0].filter(i=>i!==void 0);return`  @polyhaven/${e.id}: ${e.name} (${n.join("; ")})
+    found in ${e.matchedIn.join(", ")||"everything"}; tags ${e.tags.join(", ")}`}async function U(e,n){const i=[`${n.name} from Poly Haven (CC0, by ${n.source.authors.join(", ")||"its authors"}): ${String(n.files.length)} files in ${n.dir}/, ${n.fetched>0?`${String(n.fetched)} fetched`:"all already there"}. Records: ${n.records.join(", ")}.`];if(n.type==="model"){const r=n.main[0]??"",s=await q(e,r,await Y(A(e,r))),h=s.bounds;return i.push(h?`Measured: ${h.size.map(c=>c.toFixed(3)).join(" × ")} m along x, y (up), z; from ${h.min.map(c=>c.toFixed(3)).join(", ")} to ${h.max.map(c=>c.toFixed(3)).join(", ")}.`:`Not measured: ${s.contentsMissing??"no contents"}.`,...s.missing.length>0?[`Missing: ${s.missing.join(", ")}.`]:[],`In a scenery: const m = await w.load("${r}");`),{lines:i,model:s}}if(n.type==="hdri")return i.push(`In a scenery: await w.environment("${n.main[0]??""}", { background: true });`),{lines:i};const d=n.covers;return i.push(d&&d.length>=2?`One tile covers ${k(d[0]??0)} × ${k(d[1]??0)} (Poly Haven's dimensions): a surface's repeat is its size over that.`:"Poly Haven gives no size for one tile.",...n.main.map((r,s)=>{const h=n.maps?.[s]??"";return`  ${h}: await w.texture("${r}"${h==="diffuse"?"":', { colorSpace: "linear" }'})`})),{lines:i}}export const add=C({name:"add",summary:"Adds to the project what AllyHub and Poly Haven have, each named <type>/<name>: a starter component, a 3D model, a 3D scenery, a skill or a template from AllyHub's registry, or a CC0 model, HDRI or texture from Poly Haven; alone it lists everything AllyHub has, by type",input:p.strictObject({name:p.array(p.string()).optional().describe("What to add, each <type>/<name>: component/caption-line, 3d-model/monitor, scenery/home-desk-demo-day, skill/product-demos (a skill goes in .agents/skills, linked from .claude/skills), template/<name>, lib/<name>, or @polyhaven/<id> (as allyhub add search prints it)"),to:p.string().optional().describe(`The folder the files go in, from the project (default ${I} for a component; for an asset, its kind's folder under assets/media/ and its id)`),force:p.boolean().default(!1).describe("Replace a component's copy the project changed (its changes are lost)"),res:p.string().optional().describe(`An asset's resolution, of its textures or of the HDRI (default ${G.resolution})`),dir:oe}),positional:["name"],output:p.looseObject({}),examples:["allyhub add","allyhub add component/caption-line","allyhub add 3d-model/monitor scenery/home-desk-demo-day","allyhub add @polyhaven/metal_office_desk --res 2k"]},async(e,n)=>{const i=D(_);try{const d=await i.index();if(!e.name||e.name.length===0){const t=Math.max(...d.items.map(y=>`component/${y.name}`.length)),l=await R(n);return{value:{components:d.items,resources:l.index?.items??[]},text:["Starter components (allyhub add component/<name> copies one into components/; allyhub add search <words> finds among everything, Poly Haven's models, HDRIs and textures too):",...d.items.map(y=>`  ${`component/${y.name}`.padEnd(t)}  ${y.description}`),"",...F(l,void 0)].join(`
+`)}}const r=e.name.map(ie),s=await ne(n.cwd,e.dir),h=new Set(d.items.map(t=>t.name)),c=t=>t.type==="component"&&h.has(z(t.name)),u=r.filter(c).map(t=>z(t.name)),v=r.filter(t=>t.type==="@polyhaven").map(t=>t.name),g=r.filter(t=>t.type!=="@polyhaven"&&!c(t)),b=g.length>0?await R(n):void 0;for(const t of g){const l=b?.index?.items.find(y=>y.name===t.name);if(!l)throw new S("no-item",`There is no ${t.type}/${t.name}.`,{exit:f.notFound,hint:b?.from==="none"?"AllyHub's registry could not be read: check the connection.":`allyhub add search --type ${t.type} lists them.`});if(H(l.type)!==t.type)throw new S("usage",`${t.name} is a ${H(l.type)}, not a ${t.type}.`,{exit:f.usage,hint:`allyhub add ${E(l)}`})}const w=g.map(t=>t.name),a=[],j={};if(u.length>0){const t=e.to??I,l=await L(i,u,{root:s,dir:t,force:e.force});await T(s,l);const y=m=>m==="up to date"?"Up to date":m==="added"?"Added":"Replaced";a.push(...l.files.map(m=>`${y(m.status)} ${m.path}`));const $=l.items.find(m=>m.name===u[0]),o=$?.files[0]?.target.replaceAll("{dir}",t);if($&&o){const m=V(A(s,"name"),A(s,o)).split("\\").join("/").replace(/\.ts$/u,".js");a.push(`Import it from an item's entry file (<name>/video.ts): import { ${$.title} } from "${m.startsWith(".")?m:`./${m}`}"; one "../" more for each folder the item is deeper.`,"The file is the project's: change it as you like. allyhub add component/<name> --force puts the registry's back.")}l.missing.length>0&&a.push(`It needs packages the project does not declare: ${l.missing.join(", ")}.`),j.components=l.files.map(m=>({item:m.item,path:m.path,status:m.status})),j.missing=l.missing}if(b&&w.length>0){const t=await L(b.source,w,{root:s,dir:".",force:e.force});await T(s,t),a.length>0&&a.push(""),a.push(...t.files.map(o=>`${o.status==="up to date"?"Up to date":o.status==="added"?"Added":"Replaced"} ${o.path}`));const l=P(n);for(const o of t.assets){const m=await l.add(o.id,{root:s,...o.resolution===void 0?{}:{resolution:o.resolution},...o.maps===void 0?{}:{maps:o.maps}});a.push(...(await U(s,m)).lines)}const y=await Q(s,t.bakes);a.push(...y.map(o=>`${o.status==="added"?"Downloaded":"Up to date"} the baked light for ${o.bake.scenery}: ${o.path}`),"The files are the project's: change them as you like (a changed scenery is drawn unbaked until allyhub scenery bake bakes it again). allyhub add <type>/<name> --force puts the registry's back.");const $=t.files.filter(o=>o.path.endsWith("/README.md"));$.length>0&&a.push(`Read first, for its screens and cameras: ${$.map(o=>o.path).join(", ")}`),j.resources={files:t.files.map(o=>({item:o.item,path:o.path,status:o.status})),assets:t.assets,bakes:y.map(o=>({path:o.path,status:o.status}))}}if(v.length>0){const t=P(n),l=[];for(const y of v){const $=await t.add(y,{root:s,...e.to===void 0||u.length>0?{}:{to:B.normalize(e.to)},...e.res===void 0?{}:{resolution:e.res}}),o=await U(s,$);a.length>0&&a.push(""),a.push(...o.lines),l.push({...$,...o.model===void 0?{}:{model:o.model}})}j.assets=l}return{value:j,text:a.join(`
+`)}}catch(d){throw M(d)}}),addSearch=C({name:"add search",summary:"Finds the starter components, AllyHub's resources (models, sceneries) and Poly Haven's CC0 models, HDRIs and textures whose names, tags, categories or descriptions hold every word, each with where its words were found; with no words, lists every one",input:p.strictObject({words:p.array(p.string()).default([]).describe("The words to find (a word may start one of theirs); none lists every one"),type:p.array(p.enum(x)).optional().describe(`Only these types (default all): ${x.join(", ")} (@polyhaven: Poly Haven's models, HDRIs and textures)`),all:p.boolean().default(!1).describe(`Every match, not only the first ${String(N)} Poly Haven assets`)}),positional:["words"],output:p.looseObject({}),examples:["allyhub add search --type 3d-model",'allyhub add search "office desk" --type @polyhaven',"allyhub add search caption --type component"]},async(e,n)=>{const i=e.words.join(" ").trim(),d=i===""?"":` hold "${i}"`;try{const r=e.type??x,s=r.includes("component")?O(await D(_).index(),i):[],h=r.filter(a=>a!=="@polyhaven"),c=h.length>0?await R(n):void 0,u=c?.index?O(c.index,i).filter(a=>h.includes(H(a.type))):[],v=r.includes("@polyhaven")?se:[],{found:g,total:b}=v.length>0?await P(n).search(i,v):{found:[],total:0},w=e.all?g:g.slice(0,N);return{value:{query:i,components:s,resources:u,assets:{total:b,matches:g.length,found:w}},text:[...r.includes("component")?[`Starter components: ${String(s.length)}${d}.`,...s.map(a=>`  component/${a.name} (${a.title}): ${a.description}`)]:[],...c?c.from==="none"?F(c,[]):[`AllyHub's resources: ${String(u.length)}${d}${c.from==="stale"?" (as last read)":""}.`,...u.map(a=>`  ${E(a)} (${a.title}): ${a.description}`)]:[],...v.length>0?[`From Poly Haven (CC0): ${String(g.length)} of ${String(b)} assets${d}${w.length<g.length?`; the first ${String(w.length)} (--all for every one)`:""}.`,...w.map(de)]:[],"","Add one: allyhub add <type>/<name>"].join(`
 `)}}catch(r){throw M(r)}});

package/dist/commands/doctor.js

@@ -1,5 +1,5 @@
 /*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
-import{z as l}from"zod";import{startBrowser as j}from"@allyhub-next/browser";import{LOCAL_PACKS as A,formatBytes as d,installPack as C,localPacks as N,removePack as P}from"@allyhub-next/media";import{EXIT as g}from"@allyhub-next/protocol";import{ENCODERS as E,FFMPEG_MINIMUM as L,FFMPEG_PINNED as $,ffmpegEncoders as x,ffmpegHint as h,findFfmpeg as F}from"@allyhub-next/render";import{createPackages as w,createRuntimes as m}from"@allyhub-next/runtimes";import{defineCommand as H}from"../command.js";import{media as p,progressLines as I}from"../media.js";const f=[22,19],k=[...A,"excel","word","3d","ffmpeg","chrome"],b={excel:["exceljs"],word:["docx"],"3d":["manifold-3d","gltf-tools"]};function M(){const[e=0,o=0]=process.versions.node.split(".").map(Number),t=e>f[0]||e===f[0]&&o>=f[1];return{name:"node",ok:t,detail:`Node.js ${process.versions.node}`,...t?{}:{hint:`AllyHub needs Node.js ${f.join(".")} or newer: install it from nodejs.org or with a version manager.`}}}const y=(e,o)=>({name:o,ok:e?.available??!1,detail:e?.available?`not downloaded yet (${d(e.size)} the first time a command needs it, into ${e.dir})`:`AllyHub has no ${o} build for this computer`,...e?.available?{}:{hint:`Set ALLYHUB_${o.toUpperCase()} to one installed here.`}});async function O(e){const o=await m().locate("ffmpeg"),t=o?.bins.ffmpeg;if(t===void 0)return y(e,"ffmpeg");const s=await F(t);if(!s)return{name:"ffmpeg",ok:!1,detail:`${t} does not run`,hint:h(!0)};const a=`AllyHub needs ${L} or newer and is made with ${$}`;if(s.old)return{name:"ffmpeg",ok:!1,detail:`ffmpeg ${s.version} (${t}) is too old: ${a}`,hint:h(!0)};const r=await x(t),i=Object.entries(E).filter(([,n])=>!r.has(n)),c=[...s.pinned?[]:[`Not ${$}: its frames may differ from another computer's. ${h(!1)}`],...i.length>0?[`It cannot render ${i.map(([n,u])=>`${n} (no ${u})`).join(", ")}.`]:[]];return{name:"ffmpeg",ok:r.has("libx264"),detail:`ffmpeg ${s.version} (${t}${o?.from==="env"?", named by ALLYHUB_FFMPEG":""})`,...c.length>0?{hint:c.join(" ")}:{}}}async function R(e){if(!await m().locate("chrome"))return y(e,"chrome");try{const o=await j({gpu:!1}),t=o.product;return await o.close(),{name:"chrome",ok:!0,detail:t}}catch(o){return{name:"chrome",ok:!1,detail:`headless Chrome does not start: ${o.message.split(`
-`)[0]??""}`,hint:"Run allyhub outside the agent's sandbox, or set ALLYHUB_CHROME to another Chrome."}}}function _(e){const o=w(),t=b[e],s=t.reduce((a,r)=>a+o.size(r),0);return t.every(a=>o.locate(a)!==void 0)?`${e}: installed (${d(s)})`:`${e}: not installed (${d(s)} to download, on first use or with --install ${e})`}const G=e=>`${e.id}: ${e.unsupported??(e.installed?`installed (${d(e.bytes)})`:`not installed (${d(e.download)} to download, on first use or with --install ${e.id})`)}`;async function v(e,o,t){const s=[];for(const a of e){if(a==="ffmpeg"||a==="chrome"){const r=m();o?await r.remove(a):(t.progress(`Getting ${a}…`),await r.ensure(a,{signal:t.signal}))}else if(a==="excel"||a==="word"||a==="3d"){const r=w();for(const i of b[a])o?await r.remove(i):(t.progress(`Getting ${i}…`),await r.ensure(i,{signal:t.signal}))}else o?await p(()=>P(a)):await p(()=>C(a,{signal:t.signal,onProgress:I(t)}));s.push(`${o?"Removed":"Installed"} ${a}.`)}return s}export const doctor=H({name:"doctor",summary:"What this computer has for AllyHub: Node.js, ffmpeg, headless Chrome, the local models; --install and --remove",input:l.strictObject({install:l.array(l.enum(k)).default([]).describe("Download ahead what a command would on first use: a local pack (speech: speech recognition; people: face tracks and person mattes; reference: OCR and yt-dlp), a package (excel: workbooks; word: Word documents; 3d: building and reading models), ffmpeg or chrome"),remove:l.array(l.enum(k)).default([]).describe("Take them off this computer; a command downloads them again when it needs them")}),output:l.looseObject({ok:l.boolean(),checks:l.array(l.unknown())}),examples:["allyhub doctor","allyhub doctor --install speech"]},async(e,o)=>{const t=[...await v(e.remove,!0,o),...await v(e.install,!1,o)],s=await m().status(),a=n=>s.find(u=>u.name===n),r=[M(),await O(a("ffmpeg")),await R(a("chrome"))],i=await p(()=>N()),c=r.every(n=>n.ok);return{value:{ok:c,checks:r,packs:i,runtimes:s,changed:t},text:[...t,...r.map(n=>`${n.ok?"ok  ":"FAIL"} ${n.name}: ${n.detail}${n.hint===void 0?"":`
-     ${n.hint}`}`),...i.map(n=>`     ${G(n)}`),...["excel","word","3d"].map(n=>`     ${_(n)}`)].join(`
-`),exit:c?g.ok:g.failed}});
+import{z as l}from"zod";import{startBrowser as A}from"@allyhub-next/browser";import{LOCAL_PACKS as j,formatBytes as c,installPack as C,localPacks as N,removePack as P}from"@allyhub-next/media";import{EXIT as g}from"@allyhub-next/protocol";import{ENCODERS as E,FFMPEG_MINIMUM as L,FFMPEG_PINNED as w,ffmpegEncoders as F,ffmpegHint as u,findFfmpeg as H}from"@allyhub-next/render";import{createPackages as $,createRuntimes as m}from"@allyhub-next/runtimes";import{defineCommand as I}from"../command.js";import{media as p,progressLines as M}from"../media.js";const f=[22,19],k=[...j,"word","3d","ffmpeg","chrome"],b={word:["docx"],"3d":["manifold-3d","gltf-tools"]};function O(){const[e=0,o=0]=process.versions.node.split(".").map(Number),t=e>f[0]||e===f[0]&&o>=f[1];return{name:"node",ok:t,detail:`Node.js ${process.versions.node}`,...t?{}:{hint:`AllyHub needs Node.js ${f.join(".")} or newer: install it from nodejs.org or with a version manager.`}}}const y=(e,o)=>({name:o,ok:e?.available??!1,detail:e?.available?`not downloaded yet (${c(e.size)} the first time a command needs it, into ${e.dir})`:`AllyHub has no ${o} build for this computer`,...e?.available?{}:{hint:`Set ALLYHUB_${o.toUpperCase()} to one installed here.`}});async function R(e){const o=await m().locate("ffmpeg"),t=o?.bins.ffmpeg;if(t===void 0)return y(e,"ffmpeg");const s=await H(t);if(!s)return{name:"ffmpeg",ok:!1,detail:`${t} does not run`,hint:u(!0)};const a=`AllyHub needs ${L} or newer and is made with ${w}`;if(s.old)return{name:"ffmpeg",ok:!1,detail:`ffmpeg ${s.version} (${t}) is too old: ${a}`,hint:u(!0)};const r=await F(t),i=Object.entries(E).filter(([,n])=>!r.has(n)),d=[...s.pinned?[]:[`Not ${w}: its frames may differ from another computer's. ${u(!1)}`],...i.length>0?[`It cannot render ${i.map(([n,h])=>`${n} (no ${h})`).join(", ")}.`]:[]];return{name:"ffmpeg",ok:r.has("libx264"),detail:`ffmpeg ${s.version} (${t}${o?.from==="env"?", named by ALLYHUB_FFMPEG":""})`,...d.length>0?{hint:d.join(" ")}:{}}}async function _(e){if(!await m().locate("chrome"))return y(e,"chrome");try{const o=await A({gpu:!1}),t=o.product;return await o.close(),{name:"chrome",ok:!0,detail:t}}catch(o){return{name:"chrome",ok:!1,detail:`headless Chrome does not start: ${o.message.split(`
+`)[0]??""}`,hint:"Run allyhub outside the agent's sandbox, or set ALLYHUB_CHROME to another Chrome."}}}function G(e){const o=$(),t=b[e],s=t.reduce((a,r)=>a+o.size(r),0);return t.every(a=>o.locate(a)!==void 0)?`${e}: installed (${c(s)})`:`${e}: not installed (${c(s)} to download, on first use or with --install ${e})`}const B=e=>e.id==="speech"?`with --install ${e.id}; words are heard in the cloud without it`:`on first use or with --install ${e.id}`,S=e=>`${e.id}: ${e.unsupported??(e.installed?`installed (${c(e.bytes)})`:`not installed (${c(e.download)} to download, ${B(e)})`)}`;async function v(e,o,t){const s=[];for(const a of e){if(a==="ffmpeg"||a==="chrome"){const r=m();o?await r.remove(a):(t.progress(`Getting ${a}…`),await r.ensure(a,{signal:t.signal}))}else if(a==="word"||a==="3d"){const r=$();for(const i of b[a])o?await r.remove(i):(t.progress(`Getting ${i}…`),await r.ensure(i,{signal:t.signal}))}else o?await p(()=>P(a)):await p(()=>C(a,{signal:t.signal,onProgress:M(t)}));s.push(`${o?"Removed":"Installed"} ${a}.`)}return s}export const doctor=I({name:"doctor",summary:"What this computer has for AllyHub: Node.js, ffmpeg, headless Chrome, the local models; --install and --remove",input:l.strictObject({install:l.array(l.enum(k)).default([]).describe("Download ahead what a command would on first use: a local pack (speech: speech recognition; people: face tracks and person mattes; reference: OCR and yt-dlp), a package (excel: workbooks; word: Word documents; 3d: building and reading models), ffmpeg or chrome"),remove:l.array(l.enum(k)).default([]).describe("Take them off this computer; a command downloads them again when it needs them")}),output:l.looseObject({ok:l.boolean(),checks:l.array(l.unknown())}),examples:["allyhub doctor","allyhub doctor --install speech"]},async(e,o)=>{const t=[...await v(e.remove,!0,o),...await v(e.install,!1,o)],s=await m().status(),a=n=>s.find(h=>h.name===n),r=[O(),await R(a("ffmpeg")),await _(a("chrome"))],i=await p(()=>N()),d=r.every(n=>n.ok);return{value:{ok:d,checks:r,packs:i,runtimes:s,changed:t},text:[...t,...r.map(n=>`${n.ok?"ok  ":"FAIL"} ${n.name}: ${n.detail}${n.hint===void 0?"":`
+     ${n.hint}`}`),...i.map(n=>`     ${S(n)}`),...["word","3d"].map(n=>`     ${G(n)}`)].join(`
+`),exit:d?g.ok:g.failed}});

package/dist/commands/frames/sheet.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{readFileSync as w}from"node:fs";import{dirname as $,join as l}from"node:path";import{startBrowser as b}from"@allyhub-next/browser";import{EXIT as x}from"@allyhub-next/protocol";import{docFontsCss as S}from"@allyhub-next/render/doc";import{columnIndex as p,readArea as y,sheetHtml as A}from"@allyhub-next/sheet";import{CommandError as E}from"../../command.js";import{openSheet as M}from"../sheet.js";import{drawPage as k,picturePath as C,save as I,workPath as N}from"./common.js";export const SHEET_ROWS=200,SHEET_COLUMNS=60;const g=12;function P(e,r){const c=e.used;if(!c)return;const u=/^\$?([A-Za-z]{1,3}):\$?([A-Za-z]{1,3})$/u.exec(r);if(u){const t=p(u[1]??""),s=p(u[2]??"");return t===void 0||s===void 0?void 0:{...c,left:Math.min(t,s),right:Math.max(t,s)}}const o=/^\$?(\d+):\$?(\d+)$/u.exec(r);if(!o)return;const m=Number(o[1])-1,a=Number(o[2])-1;return{...c,top:Math.min(m,a),bottom:Math.max(m,a)}}const B=e=>e.replace(/^'|'$/gu,"").replaceAll("''","'");export async function sheetPicture(e){const{workbook:r,calc:c,file:u}=await M(e.root,e.cwd,e.item),o=$(u),m=n=>{throw new E("not-found",`${n} is not a sheet or a range of this workbook.`,{exit:x.notFound,hint:`Sheets: ${r.sheets.map(i=>i.name).join(", ")}. A range is Summary!B3:D9, or B3:D9 on the first sheet.`})};let a,t;if(e.range!==void 0){const n=r.sheet(e.range);if(n)a=[n];else{const i=e.range.lastIndexOf("!"),d=i<0?r.sheets[0]:r.sheet(B(e.range.slice(0,i))),h=e.range.slice(i+1);if(!d||(t=y(h)??P(d,h),!t))return m(e.range);a=[d]}}const s=A(c,{...a?{sheets:a}:{},...t?{area:t}:{rows:SHEET_ROWS,columns:SHEET_COLUMNS},headings:!0,css:`${await S()}body{padding:${String(g)}px}`,font:"Commissioner Variable",file:n=>{try{return new Uint8Array(w(l(e.root,o,n)))}catch{return}}}),f=await b({gpu:!1,htmlInCanvas:!1});try{const n=await k(f,{html:s.html,width:s.width+2*g}),i=e.range===void 0?"sheet":e.range.replace(/[^\p{L}\p{N}]+/gu,"-").replace(/^-+|-+$/gu,""),d=await I(C(e.cwd,e.out,l(N(e.root,"frames",o),`${i||"sheet"}.png`)),n);return{mode:"frame",source:"sheet",sheet:o,out:d,...e.range===void 0?{}:{range:e.range},cut:s.cut}}finally{await f.close()}}

package/dist/commands/frames.js

@@ -1,8 +1,9 @@
 /*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
-import{z as t}from"zod";import{formatConsole as z,formatProblem as P}from"../text/index.js";import{COMPARE_DEFAULTS as W,CUT_REVIEW_DEFAULTS as M,cutLine as I,dbText as w,silenceText as L}from"@allyhub-next/measure";import{consoleJson as x}from"@allyhub-next/project";import{PAGE_CAPTURE_DEFAULTS as $}from"@allyhub-next/browser";import{EXIT as j}from"@allyhub-next/protocol";import{defineCommand as p}from"../command.js";import{dir as k}from"../fields.js";import{parameters as T}from"../parameters.js";import{projectRoot as f}from"../project.js";import{VERSION_FIELDS as v,commandError as F,withVersion as u}from"../version.js";import{compareText as O,comparePictures as C}from"./frames/compare.js";import{isPicture as _,isVideo as E,usage as h}from"./frames/common.js";import{cutSheets as R}from"./frames/cuts.js";import{fileFrames as H}from"./frames/file.js";import{pageShot as N}from"./frames/page.js";import{pieceMoments as U,stillsSheet as G}from"./frames/piece.js";import{sizeOf as V}from"./scenery-input.js";function g(e){return[...e.problems.filter(s=>s.level==="error").map(P),...z(x(e.console))]}const b=e=>({problems:e.problems,...x(e.console)}),y=(e,a)=>f(e,a),B=t.strictObject({...v,item:t.string().optional().describe("The piece (its id, or a path into it; default the project's only one), or a video file: a path ending in .mp4, .mov, .webm, .m4v, .qt, .mkv or .avi is a file, anything else a piece"),at:t.array(t.string()).optional().describe("Moments: seconds (from the start of --part when given) or anchors (@press, @/map a stretch's end, @press+0.2); a video file's are seconds. One is written as the frame itself, several are tiled. Without it, --part's still, or every part's still on one sheet"),part:t.string().optional().describe("The part --at, --from and --to count from; alone, its still"),from:t.number().optional().describe("A stretch of consecutive frames from this second (with --to), instead of --at"),to:t.number().optional().describe("The stretch's last second"),clip:t.string().optional().describe("Write the stretch as a small silent video, .gif, .mp4 or .webm by its extension; with --out, the grid too"),overlay:t.boolean().default(!1).describe("Draw over each tile the face boxes with ids, the person matte's outline, the covered areas and the text boxes; places nothing"),beside:t.string().optional().describe("Another video file (a reference) whose frame at the same time goes on each tile's left"),grid:t.number().int().min(4).optional().describe("A video file at one --at: the frame at its own size with numbered lines every this many pixels"),out:t.string().optional().describe("Where the picture goes (a WebP); default under .allyhub/work/frames/")});function J(e){const a=[["--combo",e.combo!==void 0],["--part",e.part!==void 0],["--beside",e.beside!==void 0],["--overlay",e.overlay]].filter(([,s])=>s).map(([s])=>s);if(a.length>0)throw h("bad-option",`${a.join(" and ")} ${a.length===1?"is":"are"} a piece's: a video file has no combos or parts.`)}export const frames=p({name:"frames",summary:"Pictures of a piece over time, drawn as the render draws them: every part's still on a sheet (default), a moment, a stretch tiled or as a clip, overlays; or any video file's frames",input:B,positional:["item"],output:t.looseObject({mode:t.enum(["sheet","frame","grid","clip"])}),examples:["allyhub frames launch/film","allyhub frames launch/film --at 2.5","allyhub frames launch/film --part hook --from 0 --to 1 --clip hook.gif","allyhub frames launch/film --at 1,2,3 --overlay","allyhub frames reference.mp4 --at 0,1,2","allyhub frames reference.mp4 --at 3 --grid 50"]},async(e,a)=>{const s=a.cwd;if(e.item!==void 0&&E(e.item)){J(e);const r=await H({cwd:s,root:await y(s,e.dir),file:e.item,at:e.at,from:e.from,to:e.to,clip:e.clip,out:e.out,grid:e.grid}).catch(D=>{throw F(D)}),i=r.video,m=`${r.file} · ${i.duration.toFixed(2)} s · ${String(i.width)}×${String(i.height)} · ${String(i.fps)} fps`,S="clip"in r&&r.clip?`${r.clip.out} (${r.clip.type}, ${String(r.clip.frames)} frames at ${String(r.clip.fps)} fps, no sound)`:void 0;return{value:r,text:[m,..."out"in r?[`${r.out}${"tiles"in r?` (${String(r.tiles.length)} moments in ${String(r.cols)} columns)`:""}`]:[],...S?[S]:[]].join(`
-`)}}if(e.grid!==void 0)throw h("bad-option","--grid draws a video file's frame at its own size: give the file.");const l=await f(s,e.dir);if(!(e.at!==void 0||e.part!==void 0||e.from!==void 0||e.to!==void 0)){if(e.clip!==void 0||e.beside!==void 0||e.overlay)throw h("bad-option","--clip, --beside and --overlay draw moments: give --at, --part, or --from and --to.");const{result:r,...i}=await u(e,a,"render",m=>G(m,{cwd:s,root:l,out:e.out}));return{value:{...r,...b(i)},text:[`${r.out} (${r.piece} · ${r.format} · ${String(r.parts.length)} ${"slides"in r?"slide":"part"}${r.parts.length===1?"":"s"})`,...g(i)].join(`
-`)}}const{result:o,...d}=await u(e,a,"render",r=>U(r,{cwd:s,root:l,at:e.at,part:e.part,from:e.from,to:e.to,clip:e.clip,out:e.out,overlay:e.overlay,beside:e.beside})),c=[];if(o.mode==="frame"&&c.push(`${o.out} (${o.piece} · ${o.format} · ${o.part} · ${o.t.toFixed(2)} s)`),o.mode==="grid"){c.push(`${o.out} (${o.piece} · ${String(o.tiles.length)} moments in ${String(o.cols)} columns)`,`  ${o.tiles.map(i=>`${i.t.toFixed(o.stretch?3:2)} ${i.part}`).join(" · ")}`);const r=[...new Set(o.tiles.flatMap(i=>i.overlay?.missing??[]))];r.length>0&&c.push(`  Not measured: ${r.join(", ")}.`)}return o.stretch&&c.push(`  Stretch ${o.stretch.from.toFixed(3)}–${o.stretch.to.toFixed(3)} s, one frame in ${String(o.stretch.every)}: ${String(o.stretch.frames)} frames.`),"clip"in o&&o.clip&&c.push(`${o.clip.out} (${o.clip.type}, ${String(o.clip.frames)} frames at ${String(o.clip.fps)} fps, no sound)`),{value:{...o,...b(d)},text:[...c,...g(d)].join(`
-`)}}),framesCuts=p({name:"frames cuts",summary:"A review sheet per cut of a video (a cut take's jumps, part joins, a scenery camera's cuts): frames around it, waveform and level, the words each side, the sound at it",input:t.strictObject({...v,part:t.string().optional().describe("Only this part's cuts and its joins"),out:t.string().optional().describe("The folder the sheets go in; default .allyhub/work/cuts/"),params:T({span:t.number().positive().max(10).default(M.span).describe("Seconds shown on each side of a cut")})}),positional:["item"],output:t.looseObject({out:t.string(),cuts:t.array(t.looseObject({sheet:t.string()}))}),examples:["allyhub frames cuts launch/film","allyhub frames cuts launch/film --part hook"]},async(e,a)=>{const s=a.cwd,l=await f(s,e.dir),{result:n,...o}=await u(e,a,"render",r=>R(r,{cwd:s,root:l,part:e.part,out:e.out,review:{span:e.params.span}})),d=n.part===void 0?`${String(n.cuts.length)} cut${n.cuts.length===1?"":"s"}`:`${String(n.cuts.length)} of ${String(n.total)} cuts (part ${n.part} and its joins)`,c=[`${n.piece} · ${n.format} · ${d}; silence is sound under ${String(n.threshold)} dBFS`];for(const r of n.cuts){const i=r.sound?`level ${w(r.sound.levelDb)} / around ${w(r.sound.aroundDb)} dBFS, peak ${w(r.sound.peakDb)}, step ${r.sound.jumpDb<0?"−":"+"}${Math.abs(r.sound.jumpDb).toFixed(1)} dB`:"no sound";c.push(`${String(r.index).padStart(3)}  ${r.t.toFixed(3).padStart(7)} s  ${r.kind.padEnd(6)}  ${I(r)}`,`       silence at the cut: ${L(r.silence)} · ${i}`,`       “${r.said.before}” | “${r.said.after}”${r.across?` · across the cut: “${r.across}”`:""}`,`       ${r.sheet}`)}return{value:{...n,...b(o)},text:[...c,...g(o)].join(`
-`)}});const A=W;export const framesCompare=p({name:"frames compare",summary:"How a candidate picture differs from a reference, as numbers (ΔE, channels, SSIM, levels, grain, edges, regions) with a heatmap and a side-by-side: a piece's moment, a picture file or a video file's frame",input:t.strictObject({reference:t.string().describe("The reference picture (PNG, WebP, JPEG…)"),candidate:t.string().optional().describe("A piece (its id, or a path into it; default the project's only one) at --at or --part's still; or a file by its extension: a picture (.png, .jpg, .webp…), or a video file's frame at --at (.mp4, .mov, .webm…)"),combo:v.combo,dir:k,at:t.string().optional().describe("The moment: seconds (from the start of --part when given) or an anchor of the piece; a video file's are seconds (default 0)"),part:t.string().optional().describe("The piece's part --at counts from; alone, its still"),refCrop:t.string().optional().describe("Cut the reference to x,y,width,height, or to an element of the elements.json beside it (frames web writes one)"),crop:t.string().optional().describe("Cut the candidate to x,y,width,height before any resize"),encode:t.string().optional().describe("Draw the candidate through this encode first, as a platform serves it: codec:kbps, h264 or hevc (hevc:618)"),out:t.string().optional().describe("Where its files go, a path without extension; default under .allyhub/work/compare/"),params:T({resize:t.enum(["stretch","width","none"]).default(A.resize).describe("When sizes differ: stretch the candidate to the reference, scale it to its width, or compare the common area"),shift:t.number().int().min(0).max(32).default(A.shift).describe("Search the best offset within this many pixels each way")})}),positional:["reference","candidate"],output:t.looseObject({reference:t.string(),files:t.looseObject({side:t.string(),heatmap:t.string()})}),examples:["allyhub frames compare reference.png launch/film --at 2.5 --encode hevc:618","allyhub frames compare reference.png shot.webp --ref-crop cta","allyhub frames compare reference.png theirs.mp4 --at 3"]},async(e,a)=>{const s=a.cwd,l=e.params,n=e.candidate!==void 0&&(_(e.candidate)||E(e.candidate))?e.candidate:void 0,o=i=>({cwd:s,root:i,reference:e.reference,file:n,at:e.at===void 0?void 0:[e.at],part:e.part,refCrop:e.refCrop,crop:e.crop,encode:e.encode,out:e.out,options:{shift:l.shift,resize:l.resize}});if(n!==void 0){if(e.combo!==void 0||e.part!==void 0)throw h("bad-option","--combo and --part are a piece's: the candidate is a file.");const i=await C(o(await y(s,e.dir)),void 0).catch(m=>{throw F(m)});return{value:i,text:O(i)}}const d=await f(s,e.dir),{result:c,...r}=await u({...e,item:e.candidate},a,"render",i=>C(o(d),i));return{value:{...c,...b(r)},text:[O(c),...g(r)].join(`
-`)}}),framesWeb=p({name:"frames web",summary:"A web page's screenshot with its named elements' boxes in the image's pixels, for a screen demo",input:t.strictObject({url:t.string().describe("The page: an address, or an HTML file on this computer"),el:t.array(t.string()).optional().describe("An element to locate, name=selector (CSS, or text=<words>); [data-el] elements are found too"),click:t.array(t.string()).optional().describe("Selectors clicked in order before the shot (close a banner, open a dialog)"),full:t.boolean().default(!1).describe("The whole page, not one viewport"),out:t.string().optional().describe("Where the picture goes (a WebP), its boxes in <out>.elements.json beside it; default under .allyhub/work/pages/"),dir:k,size:t.string().default(`${String($.width)}x${String($.height)}`).describe("The viewport, WIDTHxHEIGHT in CSS pixels"),scale:t.number().min(1).max(4).default($.scale).describe("Image pixels per CSS pixel; 2 draws a high-density screen, sharp when a camera goes in"),wait:t.number().int().min(0).optional().describe("Milliseconds to wait after loading and clicking")}),positional:["url"],output:t.looseObject({out:t.string(),elementsFile:t.string()}),examples:["allyhub frames web https://example.com --el cta=text=Sign\\ up --scale 2 --out assets/media/home","allyhub frames web page.html --click '#accept' --full"]},async(e,a)=>{const s=a.cwd,[l,n]=V(e.size),o=await N({cwd:s,root:await y(s,e.dir),url:e.url,out:e.out,el:e.el,click:e.click,width:l,height:n,scale:e.scale,full:e.full,wait:e.wait});return{value:o,text:[`${o.out}: ${String(o.width)}×${String(o.height)}${o.scale===1?"":` (${String(o.scale)} image pixels per CSS pixel)`}, ${String(Object.keys(o.elements).length)} elements (${Object.keys(o.elements).join(", ")||"none"}) in ${o.elementsFile}`,...o.missing.length>0?[`Not found: ${o.missing.join(", ")} (the selector is wrong, or something must be opened with --click first).`]:[]].join(`
+import{z as t}from"zod";import{formatConsole as P,formatProblem as z}from"../text/index.js";import{COMPARE_DEFAULTS as W,CUT_REVIEW_DEFAULTS as M,cutLine as I,dbText as w,silenceText as L}from"@allyhub-next/measure";import{consoleJson as x}from"@allyhub-next/project";import{PAGE_CAPTURE_DEFAULTS as $}from"@allyhub-next/browser";import{EXIT as j}from"@allyhub-next/protocol";import{defineCommand as f}from"../command.js";import{dir as k}from"../fields.js";import{parameters as T}from"../parameters.js";import{projectRoot as u}from"../project.js";import{VERSION_FIELDS as y,commandError as F,withVersion as h}from"../version.js";import{compareText as A,comparePictures as O}from"./frames/compare.js";import{isPicture as _,isVideo as C,usage as p}from"./frames/common.js";import{cutSheets as R}from"./frames/cuts.js";import{fileFrames as B}from"./frames/file.js";import{pageShot as H}from"./frames/page.js";import{pieceMoments as N,stillsSheet as U}from"./frames/piece.js";import{sheetPicture as G}from"./frames/sheet.js";import{findSheet as V}from"./sheet.js";import{sizeOf as J}from"./scenery-input.js";function g(e){return[...e.problems.filter(s=>s.level==="error").map(z),...P(x(e.console))]}const b=e=>({problems:e.problems,...x(e.console)}),v=(e,i)=>u(e,i),q=t.strictObject({...y,item:t.string().optional().describe("The piece (its id, or a path into it; default the project's only one), a sheet, or a video file: a path ending in .mp4, .mov, .webm, .m4v, .qt, .mkv or .avi is a file"),range:t.string().optional().describe("A sheet's: what to draw, a sheet (Summary), a range (Summary!B3:D9, or B3:D9 on the first sheet), columns (A:C) or rows (1:20); default its sheets, from A1"),at:t.array(t.string()).optional().describe("Moments: seconds (from the start of --part when given) or anchors (@press, @/map a stretch's end, @press+0.2); a video file's are seconds. One is written as the frame itself, several are tiled. Without it, --part's still, or every part's still on one sheet"),part:t.string().optional().describe("The part --at, --from and --to count from; alone, its still"),from:t.number().optional().describe("A stretch of consecutive frames from this second (with --to), instead of --at"),to:t.number().optional().describe("The stretch's last second"),clip:t.string().optional().describe("Write the stretch as a small silent video, .gif, .mp4 or .webm by its extension; with --out, the grid too"),overlay:t.boolean().default(!1).describe("Draw over each tile the face boxes with ids, the person matte's outline, the covered areas and the text boxes; places nothing"),beside:t.string().optional().describe("Another video file (a reference) whose frame at the same time goes on each tile's left"),grid:t.number().int().min(4).optional().describe("A video file at one --at: the frame at its own size with numbered lines every this many pixels"),out:t.string().optional().describe("Where the picture goes (a WebP); default under .allyhub/work/frames/")});function X(e){const i=[["--combo",e.combo!==void 0],["--part",e.part!==void 0],["--beside",e.beside!==void 0],["--overlay",e.overlay]].filter(([,s])=>s).map(([s])=>s);if(i.length>0)throw p("bad-option",`${i.join(" and ")} ${i.length===1?"is":"are"} a piece's: a video file has no combos or parts.`)}export const frames=f({name:"frames",summary:"Pictures of a piece over time, drawn as the render draws them: every part's still on a sheet (default), a moment, a stretch tiled or as a clip, overlays; a sheet's cells, or a range of them; or any video file's frames",input:q,positional:["item"],output:t.looseObject({mode:t.enum(["sheet","frame","grid","clip"])}),examples:["allyhub frames launch/film","allyhub frames launch/film --at 2.5","allyhub frames launch/film --part hook --from 0 --to 1 --clip hook.gif","allyhub frames launch/film --at 1,2,3 --overlay","allyhub frames reference.mp4 --at 0,1,2","allyhub frames reference.mp4 --at 3 --grid 50","allyhub frames finance/budget --range 'Summary!A1:F20'"]},async(e,i)=>{const s=i.cwd;if(e.item!==void 0&&C(e.item)){X(e);const r=await B({cwd:s,root:await v(s,e.dir),file:e.item,at:e.at,from:e.from,to:e.to,clip:e.clip,out:e.out,grid:e.grid}).catch(D=>{throw F(D)}),a=r.video,m=`${r.file} · ${a.duration.toFixed(2)} s · ${String(a.width)}×${String(a.height)} · ${String(a.fps)} fps`,S="clip"in r&&r.clip?`${r.clip.out} (${r.clip.type}, ${String(r.clip.frames)} frames at ${String(r.clip.fps)} fps, no sound)`:void 0;return{value:r,text:[m,..."out"in r?[`${r.out}${"tiles"in r?` (${String(r.tiles.length)} moments in ${String(r.cols)} columns)`:""}`]:[],...S?[S]:[]].join(`
+`)}}if(e.grid!==void 0)throw p("bad-option","--grid draws a video file's frame at its own size: give the file.");const l=await u(s,e.dir);if(e.item!==void 0&&await V(l,s,e.item)!==void 0){const r=await G({cwd:s,root:l,item:e.item,range:e.range,out:e.out});return{value:r,text:[r.out,...r.cut].join(`
+`)}}if(e.range!==void 0)throw p("bad-option","--range is a sheet's: name the sheet.");if(!(e.at!==void 0||e.part!==void 0||e.from!==void 0||e.to!==void 0)){if(e.clip!==void 0||e.beside!==void 0||e.overlay)throw p("bad-option","--clip, --beside and --overlay draw moments: give --at, --part, or --from and --to.");const{result:r,...a}=await h(e,i,"render",m=>U(m,{cwd:s,root:l,out:e.out}));return{value:{...r,...b(a)},text:[`${r.out} (${r.piece} · ${r.format} · ${String(r.parts.length)} ${"slides"in r?"slide":"part"}${r.parts.length===1?"":"s"})`,...g(a)].join(`
+`)}}const{result:o,...d}=await h(e,i,"render",r=>N(r,{cwd:s,root:l,at:e.at,part:e.part,from:e.from,to:e.to,clip:e.clip,out:e.out,overlay:e.overlay,beside:e.beside})),c=[];if(o.mode==="frame"&&c.push(`${o.out} (${o.piece} · ${o.format} · ${o.part} · ${o.t.toFixed(2)} s)`),o.mode==="grid"){c.push(`${o.out} (${o.piece} · ${String(o.tiles.length)} moments in ${String(o.cols)} columns)`,`  ${o.tiles.map(a=>`${a.t.toFixed(o.stretch?3:2)} ${a.part}`).join(" · ")}`);const r=[...new Set(o.tiles.flatMap(a=>a.overlay?.missing??[]))];r.length>0&&c.push(`  Not measured: ${r.join(", ")}.`)}return o.stretch&&c.push(`  Stretch ${o.stretch.from.toFixed(3)}–${o.stretch.to.toFixed(3)} s, one frame in ${String(o.stretch.every)}: ${String(o.stretch.frames)} frames.`),"clip"in o&&o.clip&&c.push(`${o.clip.out} (${o.clip.type}, ${String(o.clip.frames)} frames at ${String(o.clip.fps)} fps, no sound)`),{value:{...o,...b(d)},text:[...c,...g(d)].join(`
+`)}}),framesCuts=f({name:"frames cuts",summary:"A review sheet per cut of a video (a cut take's jumps, part joins, a scenery camera's cuts): frames around it, waveform and level, the words each side, the sound at it",input:t.strictObject({...y,part:t.string().optional().describe("Only this part's cuts and its joins"),out:t.string().optional().describe("The folder the sheets go in; default .allyhub/work/cuts/"),params:T({span:t.number().positive().max(10).default(M.span).describe("Seconds shown on each side of a cut")})}),positional:["item"],output:t.looseObject({out:t.string(),cuts:t.array(t.looseObject({sheet:t.string()}))}),examples:["allyhub frames cuts launch/film","allyhub frames cuts launch/film --part hook"]},async(e,i)=>{const s=i.cwd,l=await u(s,e.dir),{result:n,...o}=await h(e,i,"render",r=>R(r,{cwd:s,root:l,part:e.part,out:e.out,review:{span:e.params.span}})),d=n.part===void 0?`${String(n.cuts.length)} cut${n.cuts.length===1?"":"s"}`:`${String(n.cuts.length)} of ${String(n.total)} cuts (part ${n.part} and its joins)`,c=[`${n.piece} · ${n.format} · ${d}; silence is sound under ${String(n.threshold)} dBFS`];for(const r of n.cuts){const a=r.sound?`level ${w(r.sound.levelDb)} / around ${w(r.sound.aroundDb)} dBFS, peak ${w(r.sound.peakDb)}, step ${r.sound.jumpDb<0?"−":"+"}${Math.abs(r.sound.jumpDb).toFixed(1)} dB`:"no sound";c.push(`${String(r.index).padStart(3)}  ${r.t.toFixed(3).padStart(7)} s  ${r.kind.padEnd(6)}  ${I(r)}`,`       silence at the cut: ${L(r.silence)} · ${a}`,`       “${r.said.before}” | “${r.said.after}”${r.across?` · across the cut: “${r.across}”`:""}`,`       ${r.sheet}`)}return{value:{...n,...b(o)},text:[...c,...g(o)].join(`
+`)}});const E=W;export const framesCompare=f({name:"frames compare",summary:"How a candidate picture differs from a reference, as numbers (ΔE, channels, SSIM, levels, grain, edges, regions) with a heatmap and a side-by-side: a piece's moment, a picture file or a video file's frame",input:t.strictObject({reference:t.string().describe("The reference picture (PNG, WebP, JPEG…)"),candidate:t.string().optional().describe("A piece (its id, or a path into it; default the project's only one) at --at or --part's still; or a file by its extension: a picture (.png, .jpg, .webp…), or a video file's frame at --at (.mp4, .mov, .webm…)"),combo:y.combo,dir:k,at:t.string().optional().describe("The moment: seconds (from the start of --part when given) or an anchor of the piece; a video file's are seconds (default 0)"),part:t.string().optional().describe("The piece's part --at counts from; alone, its still"),refCrop:t.string().optional().describe("Cut the reference to x,y,width,height, or to an element of the elements.json beside it (frames web writes one)"),crop:t.string().optional().describe("Cut the candidate to x,y,width,height before any resize"),encode:t.string().optional().describe("Draw the candidate through this encode first, as a platform serves it: codec:kbps, h264 or hevc (hevc:618)"),out:t.string().optional().describe("Where its files go, a path without extension; default under .allyhub/work/compare/"),params:T({resize:t.enum(["stretch","width","none"]).default(E.resize).describe("When sizes differ: stretch the candidate to the reference, scale it to its width, or compare the common area"),shift:t.number().int().min(0).max(32).default(E.shift).describe("Search the best offset within this many pixels each way")})}),positional:["reference","candidate"],output:t.looseObject({reference:t.string(),files:t.looseObject({side:t.string(),heatmap:t.string()})}),examples:["allyhub frames compare reference.png launch/film --at 2.5 --encode hevc:618","allyhub frames compare reference.png shot.webp --ref-crop cta","allyhub frames compare reference.png theirs.mp4 --at 3"]},async(e,i)=>{const s=i.cwd,l=e.params,n=e.candidate!==void 0&&(_(e.candidate)||C(e.candidate))?e.candidate:void 0,o=a=>({cwd:s,root:a,reference:e.reference,file:n,at:e.at===void 0?void 0:[e.at],part:e.part,refCrop:e.refCrop,crop:e.crop,encode:e.encode,out:e.out,options:{shift:l.shift,resize:l.resize}});if(n!==void 0){if(e.combo!==void 0||e.part!==void 0)throw p("bad-option","--combo and --part are a piece's: the candidate is a file.");const a=await O(o(await v(s,e.dir)),void 0).catch(m=>{throw F(m)});return{value:a,text:A(a)}}const d=await u(s,e.dir),{result:c,...r}=await h({...e,item:e.candidate},i,"render",a=>O(o(d),a));return{value:{...c,...b(r)},text:[A(c),...g(r)].join(`
+`)}}),framesWeb=f({name:"frames web",summary:"A web page's screenshot with its named elements' boxes in the image's pixels, for a screen demo",input:t.strictObject({url:t.string().describe("The page: an address, or an HTML file on this computer"),el:t.array(t.string()).optional().describe("An element to locate, name=selector (CSS, or text=<words>); [data-el] elements are found too"),click:t.array(t.string()).optional().describe("Selectors clicked in order before the shot (close a banner, open a dialog)"),full:t.boolean().default(!1).describe("The whole page, not one viewport"),out:t.string().optional().describe("Where the picture goes (a WebP), its boxes in <out>.elements.json beside it; default under .allyhub/work/pages/"),dir:k,size:t.string().default(`${String($.width)}x${String($.height)}`).describe("The viewport, WIDTHxHEIGHT in CSS pixels"),scale:t.number().min(1).max(4).default($.scale).describe("Image pixels per CSS pixel; 2 draws a high-density screen, sharp when a camera goes in"),wait:t.number().int().min(0).optional().describe("Milliseconds to wait after loading and clicking")}),positional:["url"],output:t.looseObject({out:t.string(),elementsFile:t.string()}),examples:["allyhub frames web https://example.com --el cta=text=Sign\\ up --scale 2 --out assets/media/home","allyhub frames web page.html --click '#accept' --full"]},async(e,i)=>{const s=i.cwd,[l,n]=J(e.size),o=await H({cwd:s,root:await v(s,e.dir),url:e.url,out:e.out,el:e.el,click:e.click,width:l,height:n,scale:e.scale,full:e.full,wait:e.wait});return{value:o,text:[`${o.out}: ${String(o.width)}×${String(o.height)}${o.scale===1?"":` (${String(o.scale)} image pixels per CSS pixel)`}, ${String(Object.keys(o.elements).length)} elements (${Object.keys(o.elements).join(", ")||"none"}) in ${o.elementsFile}`,...o.missing.length>0?[`Not found: ${o.missing.join(", ")} (the selector is wrong, or something must be opened with --click first).`]:[]].join(`
 `),exit:o.missing.length>0?j.failed:j.ok}}),FRAMES_COMMANDS=[frames,framesCuts,framesCompare,framesWeb];

package/dist/commands/index.js

@@ -1,2 +1,2 @@
 /*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
-import{add as o,addSearch as r}from"./add.js";import{align as m}from"./align.js";import{audio as e,audioRecording as i}from"./audio.js";import{authLogin as t,authStatus as p}from"./auth.js";import{orgsList as f}from"./orgs.js";import{check as d}from"./check.js";import{dev as s}from"./dev.js";import{doctor as a}from"./doctor.js";import{FRAMES_COMMANDS as C}from"./frames.js";import{INSPECT_COMMANDS as S}from"./inspect/index.js";import{model as c,modelCapabilities as l}from"./model.js";import{slidesCapabilities as n,slidesImport as M}from"./slides.js";import{reference as O,referenceCompare as h,referenceServed as E,referenceSetCommand as N}from"./reference.js";import{render as u}from"./render.js";import{SCENERY_COMMANDS as A}from"./scenery.js";import{sheet as D,sheetImport as R}from"./sheet.js";import{siteMediaCommand as _}from"./site.js";import{skills as g,skillsShow as k}from"./skills.js";import{CLOUD_SOURCE as v,upload as w}from"./cloud-tools.js";import{voice as I}from"./voice.js";import{words as L,wordsEdits as U}from"./words.js";export const COMMANDS=[d,...S,u,...C,e,i,D,R,s,o,r,g,k,_,L,U,m,O,h,E,N,...A,c,l,n,M,t,p,f,w,I,a],COMMAND_SOURCES=[v];
+import{add as o,addSearch as r}from"./add.js";import{align as m}from"./align.js";import{audio as e,audioRecording as i}from"./audio.js";import{authLogin as t,authStatus as p}from"./auth.js";import{orgsList as f}from"./orgs.js";import{check as s}from"./check.js";import{dev as a}from"./dev.js";import{doctor as d}from"./doctor.js";import{FRAMES_COMMANDS as C}from"./frames.js";import{INSPECT_COMMANDS as l}from"./inspect/index.js";import{model as S,modelCapabilities as c}from"./model.js";import{slidesCapabilities as M,slidesImport as h}from"./slides.js";import{reference as n,referenceCompare as O,referenceSetCommand as D}from"./reference.js";import{render as E}from"./render.js";import{SCENERY_COMMANDS as N}from"./scenery.js";import{sheet as u,sheetCalc as A,sheetCapabilities as R,sheetDiff as _,sheetImport as g,sheetTrace as b}from"./sheet.js";import{siteMediaCommand as k}from"./site.js";import{skills as w,skillsShow as I}from"./skills.js";import{CLOUD_SOURCE as L,upload as U}from"./cloud-tools.js";import{voice as v}from"./voice.js";import{words as x,wordsEdits as T}from"./words.js";export const COMMANDS=[s,...l,E,...C,e,i,u,A,b,_,R,g,a,o,r,w,I,k,x,T,m,n,O,D,...N,S,c,M,h,t,p,f,U,v,d],COMMAND_SOURCES=[L];

package/dist/commands/inspect/facts.js

@@ -1,3 +1,4 @@
 /*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
-import{z as r}from"zod";import{consoleJson as p}from"@allyhub-next/project";import{countFacts as f,filterFacts as d}from"@allyhub-next/video-core";import{defineCommand as h}from"../../command.js";import{dir as b}from"../../fields.js";import{projectRoot as u}from"../../project.js";import{formatFacts as g}from"../../text/index.js";import{checkIndexed as y,combosOf as k,commandError as j}from"../../version.js";import{HEAD as w,STRETCH as O,all as v,kind as x,kindsOf as $,pageLines as E,plural as s}from"./common.js";export const inspect=h({name:"inspect",summary:"The check's facts, for you to judge, never problems: by kind, part and time",input:r.strictObject({item:r.string().optional().describe("Only this item: its id, a path into it, or a folder of items"),combo:r.array(r.string()).optional().describe("Only combos matching name=value pairs joined with commas (lang=zh-cn,hook=b), or a combo's id (c03)"),kind:x,...O,all:v(),dir:b}),positional:["item"],output:r.looseObject({}),examples:["allyhub inspect","allyhub inspect launch/film --kind text-time,text-covered","allyhub inspect launch/film --part hook --all"]},async(t,n)=>{try{const i=await u(n.cwd,t.dir),l=$(t.kind),o=await y({dir:i,...t.item===void 0?{}:{piece:t.item},combos:k(t)},n),e=d(o.facts,{kinds:l,part:t.part,from:t.from,to:t.to}),c=o.problems.filter(a=>a.level==="error"),m=e.length===o.facts.length?s(o.facts.length,"fact"):`${s(e.length,"fact")} of ${String(o.facts.length)}`;return{value:{facts:e,counts:f(e),total:o.facts.length,problems:c,...p(o.console)},text:[`${m}: ${w}`,...g(e,{all:t.all}),...E({problems:c,console:o.console})].join(`
-`)}}catch(i){throw j(i)}});
+import{z as i}from"zod";import{consoleJson as y}from"@allyhub-next/project";import{countFacts as d,filterFacts as h}from"@allyhub-next/video-core";import{defineCommand as k}from"../../command.js";import{dir as w}from"../../fields.js";import{projectRoot as j}from"../../project.js";import{formatFacts as u}from"../../text/index.js";import{checkIndexed as v,combosOf as O,commandError as $}from"../../version.js";import{findSheet as x}from"../sheet.js";import{HEAD as b,STRETCH as F,all as S,kind as E,kindsOf as T,pageLines as z,plural as m}from"./common.js";import{projectSheetFacts as C,sheetFacts as H}from"./sheet.js";export const inspect=k({name:"inspect",summary:"The check's facts, for you to judge, never problems: by kind, part and time",input:i.strictObject({item:i.string().optional().describe("Only this item: its id, a path into it, or a folder of items"),combo:i.array(i.string()).optional().describe("Only combos matching name=value pairs joined with commas (lang=zh-cn,hook=b), or a combo's id (c03)"),kind:E,...F,all:S(),dir:w}),positional:["item"],output:i.looseObject({}),examples:["allyhub inspect","allyhub inspect launch/film --kind text-time,text-covered","allyhub inspect launch/film --part hook --all"]},async(t,c)=>{try{const o=await j(c.cwd,t.dir),a=T(t.kind),p=t.item===void 0?void 0:await x(o,c.cwd,t.item);if(p){const l=await H(o,p,{all:t.all}),s=h(l,{kinds:a});return{value:{facts:s,counts:d(s),total:l.length,problems:[]},text:[`${m(s.length,"fact")}: ${b}`,...u(s,{all:t.all})].join(`
+`)}}const r=await v({dir:o,...t.item===void 0?{}:{piece:t.item},combos:O(t)},c),e=[...r.facts,...t.item===void 0?await C(o,{all:t.all}):[]],n=h(e,{kinds:a,part:t.part,from:t.from,to:t.to}),f=r.problems.filter(l=>l.level==="error"),g=n.length===e.length?m(e.length,"fact"):`${m(n.length,"fact")} of ${String(e.length)}`;return{value:{facts:n,counts:d(n),total:e.length,problems:f,...y(r.console)},text:[`${g}: ${b}`,...u(n,{all:t.all}),...z({problems:f,console:r.console})].join(`
+`)}}catch(o){throw $(o)}});

package/dist/commands/inspect/index.js

@@ -1,2 +1,2 @@
 /*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
-import{inspectCombos as t}from"./combos.js";import{inspectContrast as o}from"./contrast.js";import{inspect as i}from"./facts.js";import{inspectFidelity as p}from"./fidelity.js";import{inspectFlash as m,inspectSeams as r}from"./joins.js";import{inspectLayout as e}from"./layout.js";import{inspectLoop as s,inspectMotion as n,inspectStill as c}from"./motion.js";import{inspectTimeline as f}from"./timeline.js";export const INSPECT_COMMANDS=[i,e,f,t,n,s,c,o,r,m,p];
+import{inspectCombos as t}from"./combos.js";import{inspectContrast as o}from"./contrast.js";import{inspect as i}from"./facts.js";import{inspectFidelity as p}from"./fidelity.js";import{inspectFlash as m,inspectSeams as r}from"./joins.js";import{inspectLayout as e}from"./layout.js";import{inspectLoop as s,inspectMotion as n,inspectStill as c}from"./motion.js";import{inspectSheet as f}from"./sheet.js";import{inspectTimeline as l}from"./timeline.js";export const INSPECT_COMMANDS=[i,e,l,t,n,s,c,o,r,m,p,f];

package/dist/commands/inspect/sheet.js

@@ -0,0 +1,3 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{join as m,relative as u}from"node:path";import{z as a}from"zod";import{scanItems as d}from"@allyhub-next/formats";import{EXIT as p}from"@allyhub-next/protocol";import{INSPECT_DEFAULTS as c,SHEET_FACT_KINDS as f,checkWorkbook as h,inspectWorkbook as b,seededRandom as y}from"@allyhub-next/sheet";import{countFacts as k,fact as g,filterFacts as w}from"@allyhub-next/video-core";import{listFiles as F}from"@allyhub-next/build";import{CommandError as j,defineCommand as N}from"../../command.js";import{dir as v}from"../../fields.js";import{projectRoot as E}from"../../project.js";import{formatFacts as S}from"../../text/index.js";import{sheetAt as x,sheetFolderName as T,sourceOfSheet as A}from"../sheet.js";import{HEAD as O,all as C,kindsOf as I,plural as $}from"./common.js";const D=(e,t)=>g(t.kind,{piece:e},t.data);export async function sheetFacts(e,t,o){const{source:n,files:s}=await A(e,t),{calc:i}=h(s,{random:y(n.text)});if(!i)return[];const r=T(e,t);return b(i,o).map(l=>D(r,l))}export async function projectSheetFacts(e,t){const{items:o}=d(await F(e)),n=[];for(const s of o)s.kind==="sheet"&&n.push(...await sheetFacts(e,m(e,s.entry),t));return n}const H=e=>e.split(",").map(t=>Number(t.trim()));export const inspectSheet=N({name:"inspect sheet",summary:"A workbook's facts, for you to judge, never problems: error values by cell, numbers written into formulas, a cell unlike its neighbours, what nothing reads, exceptions in calculated columns, values under a validation that breaks them",input:a.strictObject({sheet:a.string().describe("The sheet, by its folder or its sheet.yaml"),kind:a.array(a.string()).optional().describe(`Only facts of these kinds: ${f.join(", ")}`),plain:a.string().default(c.plain.join(",")).describe("Numbers a formula may hold and not be said, by commas; --all says them too"),around:a.number().int().min(1).default(c.around).describe("How many neighbours each side must read alike for a cell to be unlike them"),all:C("every number in every formula, and a table's columns nothing reads"),dir:v}),positional:["sheet"],output:a.looseObject({}),examples:["allyhub inspect sheet finance/budget","allyhub inspect sheet finance/budget --kind sheet-error,sheet-number","allyhub inspect sheet finance/budget --plain 0,1,100 --all"]},async(e,t)=>{const o=await E(t.cwd,e.dir),n=await x(o,t.cwd,e.sheet),s=H(e.plain);if(s.some(l=>Number.isNaN(l)))throw new j("bad-option",`${e.plain} is not numbers.`,{exit:p.usage});const i=await sheetFacts(o,n,{plain:s,around:e.around,all:e.all}),r=w(i,{kinds:I(e.kind)});return{value:{file:u(o,n),facts:r,counts:k(r),total:i.length},text:[`${$(r.length,"fact")}: ${O}`,...S(r,{all:e.all})].join(`
+`)}});

package/dist/commands/reference-text.js

@@ -1,5 +1,5 @@
 /*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
-import{INTERPRETATION_FILE as g}from"@allyhub-next/formats";import{INTERPRETATION_SHAPE as y}from"@allyhub-next/measure";import{formatProblem as j}from"../text/index.js";const m=(e,i)=>`${String(e)} ${i}${e===1?"":"s"}`,d=e=>e.toFixed(2),f=e=>`${e>=0?"+":""}${String(Math.round(e*100))}%`,l=e=>e>=0?`+${e.toFixed(2)}`:`−${(-e).toFixed(2)}`,c=(e,i=2)=>e===null?"—":String(Math.round(e*10**i)/10**i),S=(e,i=70)=>`“${e.slice(0,i)}${e.length>i?"…":""}”`,x=12;function T(e){if(!e)return"";const i=e.bitrate===void 0?"":` at ${String(Math.round(e.bitrate/1e3))} kbps`;return` · ${e.codec??""}${i}`}function P(e){const i=t=>`median ${String(t.median)} dBFS (${String(t.p10)} to ${String(t.p90)})`;return`  sound: ${e.words?`under the words ${i(e.words)}`:`whole ${i(e.whole)}`}${e.between?`; between them ${String(e.between.seconds)} s, ${i(e.between)}, ${String(Math.round(e.between.voicedShare*100))}% voiced, ${String(e.between.onsetsPerMinute)} onsets/min`:""}; floor ${String(e.floor)} dBFS`}function k(e){const i=e.motion;return`  picture: luma ${c(e.luma.p1,1)}/${c(e.luma.p50,1)}/${c(e.luma.p99,1)} (1st/50th/99th), at black ${c(e.blackShare,3)}, grain ${c(e.noise)}, sharpness ${c(e.sharpness)}, saturation ${c(e.saturation,3)}, warmth ${c(e.warmth,3)}; camera speed ${c(i.speed.p50,4)} widths/s, shake ${c(i.shake.p50,5)} widths, still ${c(i.stillShare,3)}`}function E(e){const i=n=>e.recording.spectrum.find(a=>a.hz===n)?.db,t=e.bandwidth.reach.map(n=>`−${String(n.drop)} dB at ${n.hz===null?"—":`${String(n.hz)} Hz`}`).join(", ");return`  loudness: ${c(e.loudness.integrated,1)} LUFS, range ${c(e.loudness.range,1)} LU, true peak ${c(e.loudness.truePeak,1)} dBTP; bands ${[125,500,2e3,8e3].map(n=>`${String(n)} ${String(i(n)??"—")}`).join(", ")} dB against 1 kHz; reach ${t}`}function F(e,i){const t=e.video;return[`  served: ${e.item} (${e.format}), exported as ${e.export.type}${e.export.crf===void 0?"":` crf ${String(e.export.crf)}`}${e.export.maxKbps===void 0?"":` under ${String(e.export.maxKbps)} kbit/s`}, then ${t?`${t.codec} ${String(t.width)}×${String(t.height)} ${String(t.fps)} fps at ${String(t.kbps)} kbit/s (${e.platform??""}'s served encode)`:"as exported"}; sound ${"missing"in e.audio?`${e.audio.missing}; ${e.audio.instead}`:`${e.audio.codec} ${String(e.audio.kbps)} kbit/s`}`,`    joins (where it means to cut; a cut scores ${String(i)} or more): ${e.joins.map(n=>`${d(n.t)} s ${n.kind}${n.part===void 0?"":` ${n.part}`} ${String(n.score)}${n.cut?"":" not a cut"}`).join("; ")||"none"}`,...e.unmeant.length>0?[`    cuts away from every join: ${e.unmeant.map(n=>`${d(n.t)} s ${String(n.score)}`).join("; ")}`]:[]]}export function referenceText(e,i){const t=e.reference,n=t.pacing,a=t.shots,$=e.sections,h=Math.max(4,...$.sections.map(o=>o.name.length)),u=[i(`${e.dir}/reference.json`),`  ${d(t.duration)} s · ${String(t.width)}×${String(t.height)} · ${String(t.fps)} fps${T(t.encoding)} · ${t.wordsMissing?"words missing":m(t.wordCount,"word")} · ${m(a.cuts.length,"cut")} (${String(a.weak.length)} weak; a cut scores ${String(a.threshold)} or more${a.candidates?`, all ${String(a.candidates.length)} peaks in shots.candidates`:""})`,...t.wordsMissing?[`  words: not heard (${t.wordsMissing.message}${t.wordsMissing.hint===void 0?"":` ${t.wordsMissing.hint}`}); ${t.wordsMissing.instead}`]:t.sound===void 0?["  speech: none (no sound)"]:[`  speech: ${m(t.speech.sentences.length,"sentence")}, ${m(t.speech.pauses.length,"pause")} of ${String(t.speech.pause)} s or more`],`  on-screen text: ${m(t.text.length,"line")} read in ${m(t.ocr.frames,"frame")}${t.ocr.low?.length?`; ${m(t.ocr.low.length,"word")} under confidence ${String(t.ocr.confidence.word)} in ocr.low`:""}`,...t.sound?[P(t.sound)]:[],`  pace: ${String(n.cutsPerMinute)} cuts/min, median shot ${d(n.medianShot)} s, ${String(n.wordsPerMinute)} words/min${n.timeToFirstWord===void 0?"":`, first word at ${d(n.timeToFirstWord)} s`}, text on screen ${String(Math.round(n.textShare*100))}%${n.tempo?`, tempo ${String(n.tempo.bpm)} BPM (confidence ${c(n.tempo.confidence)})`:""}`,k(t.picture),...t.audio?[E(t.audio)]:[],...t.served?F(t.served,a.threshold):[],"",$.from==="interpretation"?`  Sections (${g}):`:"  Neutral split, mechanics only (its rule is segments.rule in reference.json):",...$.sections.map(o=>`  ${o.name.padEnd(h)} ${d(o.start).padStart(6)}–${d(o.end).padEnd(6)} ${m(o.cuts.length,"cut").padEnd(7)} ${String(o.wordsPerMinute).padStart(5)} words/min  ${S(o.said)}`)];if(t.text.length>0){const o=[...t.text].sort((r,p)=>p.seconds-r.seconds||r.id-p.id).slice(0,x);u.push("",`  Text on screen, the ${String(o.length)} longest on screen of ${String(t.text.length)} (#id; reference.json's text[] has every line with its box and spans):`,...o.map(r=>`  #${String(r.id).padEnd(4)} ${S(r.text,40).padEnd(44)} y ${d(r.box[1]+r.box[3]/2)}  height ${r.height.toFixed(3)}  ${d(r.seconds).padStart(6)} s  said ${String(Math.round(r.said*100))}%`))}u.push("",`  sheets: ${e.sheets.map(i).join(", ")}`);const s=e.interpretation;return s&&"problems"in s?u.push(`  ${i(s.file)} was not used: ${s.problems.join("; ")}. Fix it and run allyhub reference ${i(e.dir)} again.`):s||u.push(`  No interpretation yet. Read the sheets and reference.json, then write ${i(`${e.dir}/${g}`)}: ${y}. allyhub reference ${i(e.dir)} then labels the sheets with its sections.`),u.join(`
-`)}export function compareText(e,i){const t=e.comparison,n=t.overall,a=n.diff,$=r=>`${r>=0?"+":""}${String(r)}`,h=(r,p,b,M)=>`  ${r.padEnd(16)} ${p.padStart(9)} → ${b.padEnd(9)} ${M}`,u=r=>r===void 0?"none":`${d(r)} s`,s=t.matches.filter(r=>!r.withinTolerance),o=e.problems.filter(r=>r.level==="error");return[`${e.piece} (${e.format}) against ${i(e.reference)}`,t.sections.from==="interpretation"?`The reference's sections are ${g}'s.`:`The reference's sections are its neutral segments (s1, s2…: a mechanical split by pauses and cuts); write ${g} beside reference.json to compare against sections of your own.`,...e.ref.wordsMissing?["The reference's words are missing: its words/min and first word read as none."]:[],t.by==="time"?`Compared by time${t.byWhy===void 0?"":` (${t.byWhy}; --by parts tries anyway)`}: each section against the same seconds of the piece, named by the parts they span.`:"Compared by parts: the piece's parts aligned to the sections (--by time for the same seconds of each).",`The piece measured from its code: ${String(t.places.filter(r=>r.cut).length)} of the ${String(t.places.length)} places its picture may cut are cuts at the reference's threshold (places in --json).`,"Per section, reference → piece (piece − reference):",...t.matches.map(r=>`  ${r.ref.names.join("+").padEnd(14)} ${d(r.ref.dur).padStart(6)} s → ${r.ours.keys.join("+").padEnd(16)} ${d(r.ours.dur).padStart(6)} s  ${l(r.diff.seconds)} s (${f(r.diff.share)})  cuts/min ${String(r.ref.cutsPerMinute)}→${String(r.ours.cutsPerMinute)}  words/min ${String(r.ref.wordsPerMinute)}→${String(r.ours.wordsPerMinute)}  text ${d(r.ref.textSeconds)}→${d(r.ours.textSeconds)} s`),"Overall:",h("duration",`${d(n.reference.duration)} s`,`${d(n.ours.duration)} s`,`${l(a.seconds)} s (${f(a.share)})`),h("cuts/min",String(n.reference.cutsPerMinute),String(n.ours.cutsPerMinute),$(a.cutsPerMinute)),h("words/min",String(n.reference.wordsPerMinute),String(n.ours.wordsPerMinute),$(a.wordsPerMinute)),h("first word",u(n.reference.timeToFirstWord),u(n.ours.timeToFirstWord),a.timeToFirstWord===void 0?"":`${l(a.timeToFirstWord)} s`),h("text on screen",`${String(Math.round(n.reference.textShare*100))}%`,`${String(Math.round(n.ours.textShare*100))}%`,`${$(Math.round(a.textShare*100))} points`),"",t.summary.meanDurationDiff===void 0?"No section matched.":`At ±${String(Math.round(t.summary.tolerance*100))}%: ${String(t.summary.sectionsWithin)} of ${String(t.summary.sections)} reference sections within, mean |duration difference| ${String(Math.round(t.summary.meanDurationDiff*100))}%${s.length?`; outside: ${s.map(r=>r.ref.names.join("+")).join(", ")}`:""}.`,`  sheet: ${i(e.sheet)}`,...o.length>0?["Must fix (the numbers may be missing where they are):",...o.map(j)]:[]].join(`
-`)}const w=e=>e===void 0||!Number.isFinite(e)?"—":String(Number(e.toPrecision(4)));export function setText(e){const i=Object.entries(e.numbers),t=i.filter(([s])=>!s.includes("[")),n=Math.min(48,Math.max(8,...t.map(([s])=>s.length))),a=e.place!==void 0,$=[`${m(e.n,"reference")}${e.where?`, labels ${e.where.map(s=>`${s.key}=${s.value}`).join(", ")}`:""}${a?`; placed: ${e.place?.id??""}`:""}`,...(e.left??[]).map(s=>`  left out: ${s.dir}: ${s.why}`),"",`${"number".padEnd(n)} ${"n".padStart(4)} ${["p10","p25","p50","p75","p90"].map(s=>s.padStart(9)).join(" ")}${a?`  ${"value".padStart(9)}  pct`:""}`,...t.map(([s,o])=>`${(s.length>n?`…${s.slice(s.length-n+1)}`:s).padEnd(n)} ${String(o.n).padStart(4)} ${[o.p10,o.p25,o.p50,o.p75,o.p90].map(p=>w(p).padStart(9)).join(" ")}${a?`  ${w(o.value).padStart(9)}  ${o.percentile===void 0?"  —":String(Math.round(o.percentile)).padStart(3)}`:""}`)];t.length<i.length&&$.push(`  and ${String(i.length-t.length)} numbers by bin (spectra, reaches, sharpness by speed, grain by light) in --json`);const h=Object.entries(e.labels);h.length>0&&$.push("",`Labels (${g}), each value's share:`,...h.map(([s,o])=>`  ${s}: ${Object.entries(o).map(([r,p])=>`${r} ${String(Math.round(p*100))}%`).join(", ")}`));const u=Object.entries(e.measuredWith).filter(([,s])=>Object.keys(s).length>1);return u.length>0&&$.push("","Measured with different parameters:",...u.map(([s,o])=>`  ${s}: ${Object.entries(o).map(([r,p])=>`${r} (${String(p)})`).join(", ")}`)),$.join(`
+import{INTERPRETATION_FILE as l}from"@allyhub-next/formats";import{INTERPRETATION_SHAPE as y}from"@allyhub-next/measure";import{formatProblem as j}from"../text/index.js";const m=(e,s)=>`${String(e)} ${s}${e===1?"":"s"}`,c=e=>e.toFixed(2),f=e=>`${e>=0?"+":""}${String(Math.round(e*100))}%`,g=e=>e>=0?`+${e.toFixed(2)}`:`−${(-e).toFixed(2)}`,d=(e,s=2)=>e===null?"—":String(Math.round(e*10**s)/10**s),S=(e,s=70)=>`“${e.slice(0,s)}${e.length>s?"…":""}”`,T=12;function P(e){if(!e)return"";const s=e.bitrate===void 0?"":` at ${String(Math.round(e.bitrate/1e3))} kbps`;return` · ${e.codec??""}${s}`}function E(e){const s=t=>`median ${String(t.median)} dBFS (${String(t.p10)} to ${String(t.p90)})`;return`  sound: ${e.words?`under the words ${s(e.words)}`:`whole ${s(e.whole)}`}${e.between?`; between them ${String(e.between.seconds)} s, ${s(e.between)}, ${String(Math.round(e.between.voicedShare*100))}% voiced, ${String(e.between.onsetsPerMinute)} onsets/min`:""}; floor ${String(e.floor)} dBFS`}function x(e){const s=e.motion;return`  picture: luma ${d(e.luma.p1,1)}/${d(e.luma.p50,1)}/${d(e.luma.p99,1)} (1st/50th/99th), at black ${d(e.blackShare,3)}, grain ${d(e.noise)}, sharpness ${d(e.sharpness)}, saturation ${d(e.saturation,3)}, warmth ${d(e.warmth,3)}; camera speed ${d(s.speed.p50,4)} widths/s, shake ${d(s.shake.p50,5)} widths, still ${d(s.stillShare,3)}`}function F(e){const s=r=>e.recording.spectrum.find(a=>a.hz===r)?.db,t=e.bandwidth.reach.map(r=>`−${String(r.drop)} dB at ${r.hz===null?"—":`${String(r.hz)} Hz`}`).join(", ");return`  loudness: ${d(e.loudness.integrated,1)} LUFS, range ${d(e.loudness.range,1)} LU, true peak ${d(e.loudness.truePeak,1)} dBTP; bands ${[125,500,2e3,8e3].map(r=>`${String(r)} ${String(s(r)??"—")}`).join(", ")} dB against 1 kHz; reach ${t}`}export function referenceText(e,s){const t=e.reference,r=t.pacing,a=t.shots,$=e.sections,h=Math.max(4,...$.sections.map(o=>o.name.length)),u=[s(`${e.dir}/reference.json`),`  ${c(t.duration)} s · ${String(t.width)}×${String(t.height)} · ${String(t.fps)} fps${P(t.encoding)} · ${t.wordsMissing?"words missing":m(t.wordCount,"word")} · ${m(a.cuts.length,"cut")} (${String(a.weak.length)} weak; a cut scores ${String(a.threshold)} or more${a.candidates?`, all ${String(a.candidates.length)} peaks in shots.candidates`:""})`,...t.wordsMissing?[`  words: not heard (${t.wordsMissing.message}${t.wordsMissing.hint===void 0?"":` ${t.wordsMissing.hint}`}); ${t.wordsMissing.instead}`]:t.sound===void 0?["  speech: none (no sound)"]:[`  speech: ${m(t.speech.sentences.length,"sentence")}, ${m(t.speech.pauses.length,"pause")} of ${String(t.speech.pause)} s or more`],`  on-screen text: ${m(t.text.length,"line")} read in ${m(t.ocr.frames,"frame")}${t.ocr.low?.length?`; ${m(t.ocr.low.length,"word")} under confidence ${String(t.ocr.confidence.word)} in ocr.low`:""}`,...t.sound?[E(t.sound)]:[],`  pace: ${String(r.cutsPerMinute)} cuts/min, median shot ${c(r.medianShot)} s, ${String(r.wordsPerMinute)} words/min${r.timeToFirstWord===void 0?"":`, first word at ${c(r.timeToFirstWord)} s`}, text on screen ${String(Math.round(r.textShare*100))}%${r.tempo?`, tempo ${String(r.tempo.bpm)} BPM (confidence ${d(r.tempo.confidence)})`:""}`,x(t.picture),...t.audio?[F(t.audio)]:[],"",$.from==="interpretation"?`  Sections (${l}):`:"  Neutral split, mechanics only (its rule is segments.rule in reference.json):",...$.sections.map(o=>`  ${o.name.padEnd(h)} ${c(o.start).padStart(6)}–${c(o.end).padEnd(6)} ${m(o.cuts.length,"cut").padEnd(7)} ${String(o.wordsPerMinute).padStart(5)} words/min  ${S(o.said)}`)];if(t.text.length>0){const o=[...t.text].sort((n,p)=>p.seconds-n.seconds||n.id-p.id).slice(0,T);u.push("",`  Text on screen, the ${String(o.length)} longest on screen of ${String(t.text.length)} (#id; reference.json's text[] has every line with its box and spans):`,...o.map(n=>`  #${String(n.id).padEnd(4)} ${S(n.text,40).padEnd(44)} y ${c(n.box[1]+n.box[3]/2)}  height ${n.height.toFixed(3)}  ${c(n.seconds).padStart(6)} s  said ${String(Math.round(n.said*100))}%`))}u.push("",`  sheets: ${e.sheets.map(s).join(", ")}`);const i=e.interpretation;return i&&"problems"in i?u.push(`  ${s(i.file)} was not used: ${i.problems.join("; ")}. Fix it and run allyhub reference ${s(e.dir)} again.`):i||u.push(`  No interpretation yet. Read the sheets and reference.json, then write ${s(`${e.dir}/${l}`)}: ${y}. allyhub reference ${s(e.dir)} then labels the sheets with its sections.`),u.join(`
+`)}export function compareText(e,s){const t=e.comparison,r=t.overall,a=r.diff,$=n=>`${n>=0?"+":""}${String(n)}`,h=(n,p,b,M)=>`  ${n.padEnd(16)} ${p.padStart(9)} → ${b.padEnd(9)} ${M}`,u=n=>n===void 0?"none":`${c(n)} s`,i=t.matches.filter(n=>!n.withinTolerance),o=e.problems.filter(n=>n.level==="error");return[`${e.piece} (${e.format}) against ${s(e.reference)}`,t.sections.from==="interpretation"?`The reference's sections are ${l}'s.`:`The reference's sections are its neutral segments (s1, s2…: a mechanical split by pauses and cuts); write ${l} beside reference.json to compare against sections of your own.`,...e.ref.wordsMissing?["The reference's words are missing: its words/min and first word read as none."]:[],t.by==="time"?`Compared by time${t.byWhy===void 0?"":` (${t.byWhy}; --by parts tries anyway)`}: each section against the same seconds of the piece, named by the parts they span.`:"Compared by parts: the piece's parts aligned to the sections (--by time for the same seconds of each).",`The piece measured from its code: ${String(t.places.filter(n=>n.cut).length)} of the ${String(t.places.length)} places its picture may cut are cuts at the reference's threshold (places in --json).`,"Per section, reference → piece (piece − reference):",...t.matches.map(n=>`  ${n.ref.names.join("+").padEnd(14)} ${c(n.ref.dur).padStart(6)} s → ${n.ours.keys.join("+").padEnd(16)} ${c(n.ours.dur).padStart(6)} s  ${g(n.diff.seconds)} s (${f(n.diff.share)})  cuts/min ${String(n.ref.cutsPerMinute)}→${String(n.ours.cutsPerMinute)}  words/min ${String(n.ref.wordsPerMinute)}→${String(n.ours.wordsPerMinute)}  text ${c(n.ref.textSeconds)}→${c(n.ours.textSeconds)} s`),"Overall:",h("duration",`${c(r.reference.duration)} s`,`${c(r.ours.duration)} s`,`${g(a.seconds)} s (${f(a.share)})`),h("cuts/min",String(r.reference.cutsPerMinute),String(r.ours.cutsPerMinute),$(a.cutsPerMinute)),h("words/min",String(r.reference.wordsPerMinute),String(r.ours.wordsPerMinute),$(a.wordsPerMinute)),h("first word",u(r.reference.timeToFirstWord),u(r.ours.timeToFirstWord),a.timeToFirstWord===void 0?"":`${g(a.timeToFirstWord)} s`),h("text on screen",`${String(Math.round(r.reference.textShare*100))}%`,`${String(Math.round(r.ours.textShare*100))}%`,`${$(Math.round(a.textShare*100))} points`),"",t.summary.meanDurationDiff===void 0?"No section matched.":`At ±${String(Math.round(t.summary.tolerance*100))}%: ${String(t.summary.sectionsWithin)} of ${String(t.summary.sections)} reference sections within, mean |duration difference| ${String(Math.round(t.summary.meanDurationDiff*100))}%${i.length?`; outside: ${i.map(n=>n.ref.names.join("+")).join(", ")}`:""}.`,`  sheet: ${s(e.sheet)}`,...o.length>0?["Must fix (the numbers may be missing where they are):",...o.map(j)]:[]].join(`
+`)}const w=e=>e===void 0||!Number.isFinite(e)?"—":String(Number(e.toPrecision(4)));export function setText(e){const s=Object.entries(e.numbers),t=s.filter(([i])=>!i.includes("[")),r=Math.min(48,Math.max(8,...t.map(([i])=>i.length))),a=e.place!==void 0,$=[`${m(e.n,"reference")}${e.where?`, labels ${e.where.map(i=>`${i.key}=${i.value}`).join(", ")}`:""}${a?`; placed: ${e.place?.id??""}`:""}`,...(e.left??[]).map(i=>`  left out: ${i.dir}: ${i.why}`),"",`${"number".padEnd(r)} ${"n".padStart(4)} ${["p10","p25","p50","p75","p90"].map(i=>i.padStart(9)).join(" ")}${a?`  ${"value".padStart(9)}  pct`:""}`,...t.map(([i,o])=>`${(i.length>r?`…${i.slice(i.length-r+1)}`:i).padEnd(r)} ${String(o.n).padStart(4)} ${[o.p10,o.p25,o.p50,o.p75,o.p90].map(p=>w(p).padStart(9)).join(" ")}${a?`  ${w(o.value).padStart(9)}  ${o.percentile===void 0?"  —":String(Math.round(o.percentile)).padStart(3)}`:""}`)];t.length<s.length&&$.push(`  and ${String(s.length-t.length)} numbers by bin (spectra, reaches, sharpness by speed, grain by light) in --json`);const h=Object.entries(e.labels);h.length>0&&$.push("",`Labels (${l}), each value's share:`,...h.map(([i,o])=>`  ${i}: ${Object.entries(o).map(([n,p])=>`${n} ${String(Math.round(p*100))}%`).join(", ")}`));const u=Object.entries(e.measuredWith).filter(([,i])=>Object.keys(i).length>1);return u.length>0&&$.push("","Measured with different parameters:",...u.map(([i,o])=>`  ${i}: ${Object.entries(o).map(([n,p])=>`${n} (${String(p)})`).join(", ")}`)),$.join(`
 `)}

package/dist/commands/reference.js

@@ -1,2 +1,2 @@
 /*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
-import{join as m,relative as W,resolve as O}from"node:path";import{z as o}from"zod";import{copyFile as _,mkdir as z,rm as J}from"node:fs/promises";import{startBrowser as U}from"@allyhub-next/browser";import{exportVersion as X}from"@allyhub-next/export";import{REFERENCE_DIR as E}from"@allyhub-next/formats";import{ReferenceError as Y,comparePiece as G,listCuts as Q,makeReference as C,readReference as Z,referenceDir as ee,referenceId as D,referenceSet as re,sceneryCuts as oe,servedCuts as te}from"@allyhub-next/measure";import{EXIT as h}from"@allyhub-next/protocol";import{encodeFor as se,encodeServed as ne,servedEncodeOf as S,servedPlatforms as F}from"@allyhub-next/render";import{comboKey as I}from"@allyhub-next/video-core";import{CommandError as k,defineCommand as j}from"../command.js";import{fresh as ie}from"../fields.js";import{fromMedia as ae,progressLines as P}from"../media.js";import{projectOfFile as ce,projectRoot as R}from"../project.js";import{VERSION_FIELDS as T,commandError as de,withVersion as B}from"../version.js";import{drawPage as L,looks as M,save as fe}from"./frames/common.js";import{compareText as le,referenceText as N,setText as me}from"./reference-text.js";function pe(e){return e instanceof Y?new k(e.code,e.message,{exit:e.kind==="usage"?h.usage:e.kind==="not-found"?h.notFound:h.failed,...e.hint===void 0?{}:{hint:e.hint}}):de(ae(e))}async function w(e){try{return await e()}catch(r){throw pe(r)}}async function V(e){let r;try{r=await U();const s=r;return await e((n,t)=>L(s,{html:n,width:t}))}finally{await r?.close()}}const A=(e,r)=>{const s=W(e,r);return s===""||s.startsWith("..")?r:s};export const reference=j({name:"reference",summary:"Measure a reference video into .allyhub/work/reference/<id>/: its words, cuts, on-screen text, pace, sound and picture as numbers, contact sheets, and reference.json; your interpretation.json beside it names its sections",input:o.strictObject({source:o.string().describe("A video file, an address yt-dlp downloads (TikTok, Instagram, YouTube…), or a reference folder (its path or id) to measure again in place"),lang:o.string().optional().describe("The language spoken, one of Parakeet's 25 European languages (en, es, fr, de…); left out, Parakeet tells them apart. One it does not cover leaves the words missing and the rest measured"),all:o.boolean().default(!1).describe("Also keep what the fixed thresholds leave out: every shot peak with its score (shots.candidates), the words OCR read with too little confidence (ocr.low) and every gap between words (speech.gaps)"),fresh:ie,dir:o.string().optional().describe("The project it goes in (default the nearest above the file, else the current folder's)")}),positional:["source"],output:o.looseObject({dir:o.string(),file:o.string(),reference:o.unknown()}),examples:["allyhub reference ~/Downloads/ad.mp4","allyhub reference https://www.tiktok.com/@brand/video/7412345678901234567","allyhub reference ad --all"]},async(e,r)=>{const s=/^https?:\/\//i.test(e.source),n=await ce(s?".":e.source,r.cwd,e.dir);n.warning!==void 0&&r.progress(n.warning);const t=await w(()=>V(c=>C(e.source,{root:n.root,cwd:r.cwd,draw:c,pictures:M(),lang:e.lang,all:e.all,fresh:e.fresh,signal:r.signal,onProgress:P(r)})));return t.reference.wordsMissing!==void 0&&r.progress(`Speech recognition failed, so the words are missing: ${t.reference.wordsMissing.message}`),{value:{dir:t.dir,file:m(t.dir,"reference.json"),video:t.video,...t.words===void 0?{}:{words:t.words},sheets:t.sheets,...t.interpretation?{interpretation:t.interpretation}:{},sections:{from:t.sections.from,list:t.sections.sections},reference:t.reference},text:N(t,c=>A(r.cwd,c))}}),referenceCompare=j({name:"reference compare",summary:"A piece measured from its code, with no render, against a reference's sections (your interpretation.json's, else its neutral segments): per section and overall, the piece's numbers less the reference's, and a side-by-side sheet",input:o.strictObject({reference:o.string().describe("The reference: its folder, its reference.json, or its id under .allyhub/work/reference/"),...T,by:o.enum(["parts","time"]).optional().describe("parts: the piece's parts aligned to the sections, by durations, places and names; time: each section against the same seconds of the piece. Default parts, time when they cannot be aligned")}),positional:["reference","item"],output:o.looseObject({reference:o.string(),sheet:o.string(),matches:o.array(o.unknown())}),examples:["allyhub reference compare ad launch/film","allyhub reference compare .allyhub/work/reference/ad launch/film --by time"]},async(e,r)=>{const s=await R(r.cwd,e.dir),n=await ee(s,r.cwd,e.reference);if(n===void 0)throw new k("no-reference",`There is no reference ${e.reference}: no reference.json at ${O(r.cwd,e.reference)} or in ${m(E,e.reference)}.`,{exit:h.notFound,hint:"Make it with allyhub reference <file or URL>."});const t=await w(()=>Z(n)),c=await B(e,r,"render",async i=>{r.progress(`Measuring ${i.target.piece} from its code`);const{comparison:f,sheet:d}=await w(()=>G(i,{ref:t.ref,video:t.video,words:t.words,interpretation:t.interpretation,by:e.by,draw:(l,g)=>L(i.session.browser,{html:l,width:g})})),a=I(i.target.combo),u=await fe(m(n,`compare.${i.target.piece.replaceAll("/","-")}${a==="default"?"":`.${a}`}.${M()}`),d);return{piece:i.target.piece,combo:i.target.combo,format:i.target.format,sheet:u,comparison:f}}),p=c.result;return{value:{reference:n,...t.ref.wordsMissing?{referenceWordsMissing:t.ref.wordsMissing}:{},piece:p.piece,combo:p.combo,format:p.format,sheet:p.sheet,...p.comparison,problems:c.problems.filter(i=>i.level==="error")},text:le({...p,reference:n,ref:t.ref,problems:c.problems},i=>A(r.cwd,i))}}),referenceServed=j({name:"reference served",summary:"A piece measured as a platform serves it: rendered as its export (through the part cache), encoded as the platform's served encode, and measured as a reference is, with where it means to cut against the cuts found",input:o.strictObject({...T,platform:o.string().optional().describe(`The platform whose served encode it goes through: ${F().join(", ")||"none measured yet"}; none measures the export itself. Default the piece's format's, when AllyHub has measured it`)}),positional:["item"],output:o.looseObject({dir:o.string(),file:o.string(),reference:o.unknown()}),examples:["allyhub reference served launch/film-tiktok","allyhub reference served launch/film --platform tiktok"]},async(e,r)=>{const s=await R(r.cwd,e.dir);if(e.platform!==void 0&&e.platform!=="none"&&S(e.platform)===void 0)throw new k("bad-option",`AllyHub has no served encode for ${e.platform}.`,{exit:h.usage,hint:`Measured: ${F().join(", ")||"none"}; --platform none measures the export itself.`});const n=await B(e,r,"render",async d=>{const a=d.target,u=e.platform==="none"?void 0:e.platform??(S(a.format)===void 0?void 0:a.format),l=u===void 0?void 0:S(u),g=I(a.combo),b=m(s,E,[D(a.piece),...g==="default"?[]:[D(g)],u??"export"].join("-"));await z(b,{recursive:!0});const $=m(b,"export.mp4");r.progress(`Rendering ${a.piece} as exported`);const q=await X(d,"mp4",$),y=m(b,"video.mp4");let x;l?(r.progress(`Encoding it as ${u??""} serves it: h264 ${String(l.video.width)}×${String(l.video.height)} at ${String(l.video.kbps)} kbit/s, ${l.audio.codec} at ${String(l.audio.kbps)} kbit/s`),x=await ne({from:$,to:y,e:l,noSound:q.loudness===void 0,root:s})):(await J(y,{force:!0}),await _($,y),x={missing:"measured as exported (--platform none)",instead:"the export's own sound"});const v=se("mp4",a.format,{},d.timeline),H={item:a.piece,combo:{...a.combo},format:a.format,...u===void 0?{}:{platform:u},export:{type:"mp4",...v.crf===void 0?{}:{crf:v.crf},...v.maxBitrate===void 0?{}:{maxKbps:v.maxBitrate}},...l?{video:{...l.video}}:{},audio:x},K=Q(d.timeline,d.prepared.media,await oe(d.version));return{dir:b,video:y,conditions:H,cuts:K}}),{dir:t,video:c,conditions:p,cuts:i}=n.result,f=await w(()=>V(d=>C(c,{root:s,cwd:r.cwd,dir:t,draw:d,pictures:M(),all:!0,signal:r.signal,onProgress:P(r),served:async a=>({...p,...await te(c,a,i,{root:s})})})));return{value:{dir:f.dir,file:m(f.dir,"reference.json"),video:f.video,export:m(f.dir,"export.mp4"),sheets:f.sheets,sections:{from:f.sections.from,list:f.sections.sections},reference:f.reference},text:N(f,d=>A(r.cwd,d))}});function ue(e){const r=e.indexOf("=");if(r<=0)throw new k("bad-option",`--where takes label=value, not ${JSON.stringify(e)}.`,{exit:h.usage});return{key:e.slice(0,r),value:e.slice(r+1)}}export const referenceSetCommand=j({name:"reference set",summary:"A set of references as statistics: every number their reference.json holds, by its path, with its quantiles; each value's share of their interpretation.json labels; and one folder's percentile among them",input:o.strictObject({folders:o.array(o.string()).optional().describe("Reference folders, or folders of them (default the project's .allyhub/work/reference/)"),where:o.array(o.string()).optional().describe("Only the references whose interpretation.json labels hold this, label=value (a list holds what it contains)"),place:o.string().optional().describe("A reference folder to place among the set: each of its numbers with its percentile (a piece measured with allyhub reference served)"),dir:T.dir}),positional:["folders"],output:o.looseObject({n:o.number(),numbers:o.unknown()}),examples:["allyhub reference set","allyhub reference set --where format=talking-head --place .allyhub/work/reference/film-tiktok"]},async(e,r)=>{const s=e.folders===void 0||e.folders.length===0?await R(r.cwd,e.dir):void 0,n=s===void 0?(e.folders??[]).map(c=>O(r.cwd,c)):[m(s,E)],t=await w(()=>re(n,{place:e.place===void 0?void 0:O(r.cwd,e.place),where:(e.where??[]).map(ue)}));return{value:{...t},text:me(t)}});
+import{join as d,relative as $,resolve as m}from"node:path";import{z as s}from"zod";import{startBrowser as M}from"@allyhub-next/browser";import{REFERENCE_DIR as w}from"@allyhub-next/formats";import{ReferenceError as A,comparePiece as C,makeReference as D,readReference as I,referenceDir as S,referenceSet as F}from"@allyhub-next/measure";import{EXIT as l}from"@allyhub-next/protocol";import{comboKey as P}from"@allyhub-next/video-core";import{cloudHearing as L}from"../cloud-hearing.js";import{CommandError as h,defineCommand as u}from"../command.js";import{fresh as N}from"../fields.js";import{fromMedia as q,progressLines as x}from"../media.js";import{projectOfFile as V,projectRoot as b}from"../project.js";import{VERSION_FIELDS as g,commandError as W,withVersion as _}from"../version.js";import{drawPage as y,looks as k,save as z}from"./frames/common.js";import{compareText as B,referenceText as H,setText as J}from"./reference-text.js";function K(e){return e instanceof A?new h(e.code,e.message,{exit:e.kind==="usage"?l.usage:e.kind==="not-found"?l.notFound:l.failed,...e.hint===void 0?{}:{hint:e.hint}}):W(q(e))}async function f(e){try{return await e()}catch(r){throw K(r)}}async function U(e){let r;try{r=await M();const n=r;return await e((t,o)=>y(n,{html:t,width:o}))}finally{await r?.close()}}const j=(e,r)=>{const n=$(e,r);return n===""||n.startsWith("..")?r:n};export const reference=u({name:"reference",summary:"Measure a reference video into .allyhub/work/reference/<id>/: its words, cuts, on-screen text, pace, sound and picture as numbers, contact sheets, and reference.json; your interpretation.json beside it names its sections",input:s.strictObject({source:s.string().describe("A video file, an address yt-dlp downloads (TikTok, Instagram, YouTube…), or a reference folder (its path or id) to measure again in place"),lang:s.string().optional().describe("The language spoken, one of Parakeet's 25 European languages (en, es, fr, de…); left out, Parakeet tells them apart. One it does not cover leaves the words missing and the rest measured"),all:s.boolean().default(!1).describe("Also keep what the fixed thresholds leave out: every shot peak with its score (shots.candidates), the words OCR read with too little confidence (ocr.low) and every gap between words (speech.gaps)"),fresh:N,dir:s.string().optional().describe("The project it goes in (default the nearest above the file, else the current folder's)")}),positional:["source"],output:s.looseObject({dir:s.string(),file:s.string(),reference:s.unknown()}),examples:["allyhub reference ~/Downloads/ad.mp4","allyhub reference https://www.tiktok.com/@brand/video/7412345678901234567","allyhub reference ad --all"]},async(e,r)=>{const n=/^https?:\/\//i.test(e.source),t=await V(n?".":e.source,r.cwd,e.dir);t.warning!==void 0&&r.progress(t.warning);const o=await f(()=>U(i=>D(e.source,{root:t.root,cwd:r.cwd,draw:i,pictures:k(),lang:e.lang,cloud:L(r,t.root),all:e.all,fresh:e.fresh,signal:r.signal,onProgress:x(r)})));return o.reference.wordsMissing!==void 0&&r.progress(`Speech recognition failed, so the words are missing: ${o.reference.wordsMissing.message}`),{value:{dir:o.dir,file:d(o.dir,"reference.json"),video:o.video,...o.words===void 0?{}:{words:o.words},sheets:o.sheets,...o.interpretation?{interpretation:o.interpretation}:{},sections:{from:o.sections.from,list:o.sections.sections},reference:o.reference},text:H(o,i=>j(r.cwd,i))}}),referenceCompare=u({name:"reference compare",summary:"A piece measured from its code, with no render, against a reference's sections (your interpretation.json's, else its neutral segments): per section and overall, the piece's numbers less the reference's, and a side-by-side sheet",input:s.strictObject({reference:s.string().describe("The reference: its folder, its reference.json, or its id under .allyhub/work/reference/"),...g,by:s.enum(["parts","time"]).optional().describe("parts: the piece's parts aligned to the sections, by durations, places and names; time: each section against the same seconds of the piece. Default parts, time when they cannot be aligned")}),positional:["reference","item"],output:s.looseObject({reference:s.string(),sheet:s.string(),matches:s.array(s.unknown())}),examples:["allyhub reference compare ad launch/film","allyhub reference compare .allyhub/work/reference/ad launch/film --by time"]},async(e,r)=>{const n=await b(r.cwd,e.dir),t=await S(n,r.cwd,e.reference);if(t===void 0)throw new h("no-reference",`There is no reference ${e.reference}: no reference.json at ${m(r.cwd,e.reference)} or in ${d(w,e.reference)}.`,{exit:l.notFound,hint:"Make it with allyhub reference <file or URL>."});const o=await f(()=>I(t)),i=await _(e,r,"render",async a=>{r.progress(`Measuring ${a.target.piece} from its code`);const{comparison:v,sheet:O}=await f(()=>C(a,{ref:o.ref,video:o.video,words:o.words,interpretation:o.interpretation,by:e.by,draw:(R,T)=>y(a.session.browser,{html:R,width:T})})),p=P(a.target.combo),E=await z(d(t,`compare.${a.target.piece.replaceAll("/","-")}${p==="default"?"":`.${p}`}.${k()}`),O);return{piece:a.target.piece,combo:a.target.combo,format:a.target.format,sheet:E,comparison:v}}),c=i.result;return{value:{reference:t,...o.ref.wordsMissing?{referenceWordsMissing:o.ref.wordsMissing}:{},piece:c.piece,combo:c.combo,format:c.format,sheet:c.sheet,...c.comparison,problems:i.problems.filter(a=>a.level==="error")},text:B({...c,reference:t,ref:o.ref,problems:i.problems},a=>j(r.cwd,a))}});function X(e){const r=e.indexOf("=");if(r<=0)throw new h("bad-option",`--where takes label=value, not ${JSON.stringify(e)}.`,{exit:l.usage});return{key:e.slice(0,r),value:e.slice(r+1)}}export const referenceSetCommand=u({name:"reference set",summary:"A set of references as statistics: every number their reference.json holds, by its path, with its quantiles; each value's share of their interpretation.json labels; and one folder's percentile among them",input:s.strictObject({folders:s.array(s.string()).optional().describe("Reference folders, or folders of them (default the project's .allyhub/work/reference/)"),where:s.array(s.string()).optional().describe("Only the references whose interpretation.json labels hold this, label=value (a list holds what it contains)"),place:s.string().optional().describe("A reference folder to place among the set: each of its numbers with its percentile (a piece measured with allyhub reference served)"),dir:g.dir}),positional:["folders"],output:s.looseObject({n:s.number(),numbers:s.unknown()}),examples:["allyhub reference set","allyhub reference set --where format=talking-head --place .allyhub/work/reference/film-tiktok"]},async(e,r)=>{const n=e.folders===void 0||e.folders.length===0?await b(r.cwd,e.dir):void 0,t=n===void 0?(e.folders??[]).map(i=>m(r.cwd,i)):[d(n,w)],o=await f(()=>F(t,{place:e.place===void 0?void 0:m(r.cwd,e.place),where:(e.where??[]).map(X)}));return{value:{...o},text:J(o)}});

package/dist/commands/render.js

@@ -1,3 +1,3 @@
 /*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
-import{join as x,resolve as g}from"node:path";import{z as t}from"zod";import{formatConsole as y,formatProblem as w}from"../text/index.js";import{exportProject as v}from"@allyhub-next/export";import{SHARE_ENCODE as n}from"@allyhub-next/render";import{consoleJson as m}from"@allyhub-next/project";import{OUT_DIR as k}from"@allyhub-next/formats";import{EXIT as p}from"@allyhub-next/protocol";import{defineCommand as $}from"../command.js";import{parameters as P}from"../parameters.js";import{projectRoot as O}from"../project.js";import{combosOf as j,commandError as B}from"../version.js";import{dir as S,indexing as A}from"../fields.js";const T={codec:t.enum(["h264","h265"]).default("h264").describe("The mp4's video codec; h265 is smaller"),crf:t.number().int().min(0).max(63).optional().describe(`Quality, lower is better: default ${String(n.crf)} for an mp4, ready to share (a platform profile's format its own), 30 for a webm`),maxBitrate:t.number().int().min(0).max(5e5).optional().describe(`An mp4's most video bitrate, kbit/s, 0 for none: default ${String(n.maxKbps)} at 1080p ${String(n.fps)} fps, scaled by the frame's pixels and the frames a second (16000 at 1080p 60, 32000 at 4K 30), so the file is ready to share; a platform profile's format its own`),audioBitrate:t.number().int().min(32).max(512).optional().describe("The sound's bitrate, kbit/s: default 192 (AAC in an mp4), 160 (Opus in a webm); a mov keeps PCM"),steps:t.boolean().default(!1).describe("A deck's pdf, png and pptx: a page, a file or a slide per step of each page, not only its last"),pptx:t.enum(["native","picture","editable"]).default("native").describe("A deck's pptx: native, PowerPoint's own model (the deck's masters, layouts, placeholders, shapes, text, pictures, videos and notes, a component as its picture); picture, each slide a picture of the page; or editable, the page's picture without its text under a text box per block of text")},D=(o,s)=>`${String(o)} ${s}${o===1?"":"s"}`;export const render=$({name:"render",summary:"The files: a video, its frames, subtitles, cover and mastered mix; a batch's table of ads; a deck's PDF, PPTX and PNGs; a doc's PDF and Markdown; a sheet's xlsx, CSV, Markdown and JSON; a 3D model's GLB",input:t.strictObject({items:t.array(t.string()).optional().describe("Only these items: an id, a path into one, or a folder of items; default every one"),combo:t.array(t.string()).optional().describe("Only the combos matching name=value pairs joined with commas (lang=zh-cn,hook=b), or a combo's id (c03)"),type:t.array(t.string()).optional().describe("File types: mp4, mov, webm, gif, png, srt, vtt (cues cut as the piece's captions layer cuts them, else by default), cover, wav (the mix, mastered as the render masters it: 48 kHz, 16 bits, the film's length), pdf, pptx; csv for a piece with slots, its table of ads (<piece>/ads.csv: a row per ad with its combo, picks, length, file, name and generated media); a doc's pdf, docx, png, md; a sheet's xlsx, csv, md, json; a 3D model's glb. Default mp4 for a video, pdf for a deck and a doc, xlsx for a sheet, glb for a model; a type an item does not have is skipped"),out:t.string().optional().describe("The folder the files go in; default .allyhub/out"),name:t.string().optional().describe("Name a video's or deck's files <name>.<ext> in its folder of the output, with what tells its versions apart before the extension when there are several (<name>.zh-cn.mp4, <name>.c03.mp4); default <output>.<combo>.<ext>"),params:P(T),dir:S}),positional:["items"],output:t.looseObject({out:t.string(),files:t.array(t.looseObject({name:t.string(),path:t.string(),type:t.string()})),failed:t.array(t.looseObject({name:t.string(),code:t.string()}))}),examples:["allyhub render","allyhub render launch/film --type mp4,srt","allyhub render launch/film --type wav","allyhub render ads/tidyform --type csv","allyhub render launch/plan --type pdf,md","allyhub render launch/deck --type pptx --param pptx=editable","allyhub render --combo lang=zh-cn --param crf=16","allyhub render launch/film --name launch-film --param max-bitrate=0"]},async(o,s)=>{const d=await O(s.cwd,o.dir),c=g(s.cwd,o.out??x(d,k)),r=o.params,f={codec:r.codec,...r.crf===void 0?{}:{crf:r.crf},...r.maxBitrate===void 0?{}:{maxBitrate:r.maxBitrate},...r.audioBitrate===void 0?{}:{audioBitrate:r.audioBitrate}};let a;try{a=await v({root:d,out:c,...o.items===void 0?{}:{items:o.items},combos:j(o),...o.type===void 0?{}:{types:o.type},...o.name===void 0?{}:{name:o.name},encode:f,...r.steps?{steps:!0}:{},...r.pptx==="native"?{}:{pptx:r.pptx},index:A(s.env),log:e=>{s.progress(e)},signal:s.signal})}catch(e){throw B(e)}const h=e=>e?` (${e.integrated.toFixed(1)} LUFS, true peak ${e.truePeak===void 0?"–":e.truePeak.toFixed(1)} dBTP)`:"",u=a.problems.filter(e=>e.level==="error"),l=a.files.flatMap(e=>e.files.length>1?e.files.map(i=>`  ${i}`):[`  ${e.path}${h(e.loudness)}`]),b=[`${D(l.length,"file")} in ${a.out}:`,...l,...a.failed.length>0?["Not made:",...a.failed.map(e=>`  ${e.name}: ${e.message}${e.hint?` ${e.hint}`:""}`)]:[],...a.unindexed.map(e=>`Not indexed, drawn the fallback way: ${e.file} (${e.error})`),...new Set(a.files.flatMap(e=>(e.fontsLeft??[]).map(i=>`Not in the file: ${i.font} (${i.why}); PowerPoint shows another font where it is not installed.`))),...u.map(w),...y(m(a.console))];return{value:{out:a.out,files:a.files.map(e=>({...e})),failed:a.failed.map(e=>({...e})),problems:a.problems,...a.unindexed.length>0?{unindexed:a.unindexed}:{},...m(a.console)},text:b.join(`
-`),exit:a.failed.length>0?p.failed:p.ok}});
+import{join as x,resolve as y}from"node:path";import{z as t}from"zod";import{formatConsole as w,formatProblem as v}from"../text/index.js";import{exportProject as k}from"@allyhub-next/export";import{SHARE_ENCODE as n}from"@allyhub-next/render";import{consoleJson as p}from"@allyhub-next/project";import{OUT_DIR as $}from"@allyhub-next/formats";import{EXIT as c}from"@allyhub-next/protocol";import{defineCommand as P}from"../command.js";import{parameters as O}from"../parameters.js";import{projectRoot as S}from"../project.js";import{combosOf as j,commandError as B}from"../version.js";import{dir as A,indexing as D}from"../fields.js";const N={codec:t.enum(["h264","h265"]).default("h264").describe("The mp4's video codec; h265 is smaller"),crf:t.number().int().min(0).max(63).optional().describe(`Quality, lower is better: default ${String(n.crf)} for an mp4, ready to share (a platform profile's format its own), 30 for a webm`),maxBitrate:t.number().int().min(0).max(5e5).optional().describe(`An mp4's most video bitrate, kbit/s, 0 for none: default ${String(n.maxKbps)} at 1080p ${String(n.fps)} fps, scaled by the frame's pixels and the frames a second (16000 at 1080p 60, 32000 at 4K 30), so the file is ready to share; a platform profile's format its own`),audioBitrate:t.number().int().min(32).max(512).optional().describe("The sound's bitrate, kbit/s: default 192 (AAC in an mp4), 160 (Opus in a webm); a mov keeps PCM"),steps:t.boolean().default(!1).describe("A deck's pdf, png and pptx: a page, a file or a slide per step of each page, not only its last"),pptx:t.enum(["native","picture","editable"]).default("native").describe("A deck's pptx: native, PowerPoint's own model (the deck's masters, layouts, placeholders, shapes, text, pictures, videos and notes, a component as its picture); picture, each slide a picture of the page; or editable, the page's picture without its text under a text box per block of text")},T=(o,i)=>`${String(o)} ${i}${o===1?"":"s"}`;export const render=P({name:"render",summary:"The files: a video, its frames, subtitles, cover and mastered mix; a batch's table of ads; a deck's PDF, PPTX and PNGs; a doc's PDF and Markdown; a sheet's Excel workbook with live formulas, PDF, PNG, CSV, Markdown and JSON; a 3D model's GLB",input:t.strictObject({items:t.array(t.string()).optional().describe("Only these items: an id, a path into one, or a folder of items; default every one"),combo:t.array(t.string()).optional().describe("Only the combos matching name=value pairs joined with commas (lang=zh-cn,hook=b), or a combo's id (c03)"),type:t.array(t.string()).optional().describe("File types: mp4, mov, webm, gif, png, srt, vtt (cues cut as the piece's captions layer cuts them, else by default), cover, wav (the mix, mastered as the render masters it: 48 kHz, 16 bits, the film's length), pdf, pptx; csv for a piece with slots, its table of ads (<piece>/ads.csv: a row per ad with its combo, picks, length, file, name and generated media); a doc's pdf, docx, png, md; a sheet's xlsx (every sheet, formulas live with their values cached), pdf, png, csv, md, json; a 3D model's glb. Default mp4 for a video, pdf for a deck and a doc, xlsx for a sheet, glb for a model; a type an item does not have is skipped"),out:t.string().optional().describe("The folder the files go in; default .allyhub/out"),name:t.string().optional().describe("Name a video's or deck's files <name>.<ext> in its folder of the output, with what tells its versions apart before the extension when there are several (<name>.zh-cn.mp4, <name>.c03.mp4); default <output>.<combo>.<ext>"),params:O(N),dir:A}),positional:["items"],output:t.looseObject({out:t.string(),files:t.array(t.looseObject({name:t.string(),path:t.string(),type:t.string()})),failed:t.array(t.looseObject({name:t.string(),code:t.string()}))}),examples:["allyhub render","allyhub render launch/film --type mp4,srt","allyhub render launch/film --type wav","allyhub render ads/tidyform --type csv","allyhub render launch/plan --type pdf,md","allyhub render finance/budget --type xlsx,pdf","allyhub render launch/deck --type pptx --param pptx=editable","allyhub render --combo lang=zh-cn --param crf=16","allyhub render launch/film --name launch-film --param max-bitrate=0"]},async(o,i)=>{const d=await S(i.cwd,o.dir),f=y(i.cwd,o.out??x(d,$)),r=o.params,h={codec:r.codec,...r.crf===void 0?{}:{crf:r.crf},...r.maxBitrate===void 0?{}:{maxBitrate:r.maxBitrate},...r.audioBitrate===void 0?{}:{audioBitrate:r.audioBitrate}};let l=0,a;try{a=await k({root:d,out:f,...o.items===void 0?{}:{items:o.items},combos:j(o),...o.type===void 0?{}:{types:o.type},...o.name===void 0?{}:{name:o.name},encode:h,...r.steps?{steps:!0}:{},...r.pptx==="native"?{}:{pptx:r.pptx},index:D(i.env),log:e=>{i.progress(e)},onProgress:e=>{const s=Math.floor(e*10);s<=l||s>=10||(l=s,i.progress(`${String(s*10)}%`))},signal:i.signal})}catch(e){throw B(e)}const u=e=>e?` (${e.integrated.toFixed(1)} LUFS, true peak ${e.truePeak===void 0?"–":e.truePeak.toFixed(1)} dBTP)`:"",b=a.problems.filter(e=>e.level==="error"),m=a.files.flatMap(e=>e.files.length>1?e.files.map(s=>`  ${s}`):[`  ${e.path}${u(e.loudness)}`]),g=[`${T(m.length,"file")} in ${a.out}:`,...m,...a.failed.length>0?["Not made:",...a.failed.map(e=>`  ${e.name}: ${e.message}${e.hint?` ${e.hint}`:""}`)]:[],...a.unindexed.map(e=>`Not indexed, drawn the fallback way: ${e.file} (${e.error})`),...new Set(a.files.flatMap(e=>(e.fontsLeft??[]).map(s=>`Not in the file: ${s.font} (${s.why}); PowerPoint shows another font where it is not installed.`))),...b.map(v),...w(p(a.console))];return{value:{out:a.out,files:a.files.map(e=>({...e})),failed:a.failed.map(e=>({...e})),problems:a.problems,...a.unindexed.length>0?{unindexed:a.unindexed}:{},...p(a.console)},text:g.join(`
+`),exit:a.failed.length>0?c.failed:c.ok}});

package/dist/commands/sheet.js

@@ -1,4 +1,8 @@
 /*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
-import{mkdir as M,readFile as b,stat as S,writeFile as k}from"node:fs/promises";import{basename as x,dirname as v,join as l,relative as I,resolve as T}from"node:path";import{z as m}from"zod";import{ITEM_KINDS as N,SHEET_SPEC as j}from"@allyhub-next/formats";import{EXIT as w}from"@allyhub-next/protocol";import{createPackages as V}from"@allyhub-next/runtimes";import{importSheets as L,PROFILE_TOP as P,profileSheet as _,readSheet as E,readSpec as A}from"@allyhub-next/sheet";import{CommandError as p,defineCommand as F}from"../command.js";import{projectRoot as O}from"../project.js";import{dir as C}from"../fields.js";const u=N.sheet.entries[0];async function D(e,n,o){const s=T(n,o);for(const t of[x(s)===u?s:l(s,u),l(e,o,u)])if((await S(t).catch(()=>{}))?.isFile())return t;throw new p("not-found",`There is no sheet ${o}.`,{exit:w.notFound,hint:"Name it by its folder (research/leads) or its sheet.csv."})}const d=e=>e.toLocaleString("en-US"),y=e=>e.toLocaleString("en-US",{maximumFractionDigits:4});function R(e,n){const o=[`${d(e.empty)} empty`,`${d(e.distinct)} distinct`];if(e.unreadable>0&&o.push(`${d(e.unreadable)} unreadable`),e.min!==void 0&&e.max!==void 0){const t=r=>typeof r=="number"?y(r):r;o.push(`${t(e.min)} to ${t(e.max)}`)}e.sum!==void 0&&o.push(`sum ${y(e.sum)}`),e.mean!==void 0&&o.push(`mean ${y(e.mean)}`),e.shortest!==void 0&&e.longest!==void 0&&o.push(`${String(e.shortest)} to ${String(e.longest)} characters`);const s=[`${e.name.padEnd(n)}  ${e.type.padEnd(12)}  ${o.join(", ")}`];return e.values?.some(t=>t.count>1)&&s.push(`${"".padEnd(n+14)}  most: ${e.values.map(t=>`${JSON.stringify(t.value.length>40?`${t.value.slice(0,39)}…`:t.value)} ${d(t.count)}`).join(", ")}`),s}const U=m.string().transform(e=>e.replace(/^\/+|\/+$/gu,"")).refine(e=>e!==""&&!e.split("/").some(n=>n===""||n==="."||n===".."),{message:"a folder from the project's root, such as research/leads"});async function q(){const{default:e}=await V().load("exceljs");return e}export const sheet=F({name:"sheet",summary:"A sheet's columns measured: counts, empty, distinct, ranges, frequent values",input:m.strictObject({sheet:m.string().describe("The sheet, by its folder or its sheet.csv"),dir:C}),positional:["sheet"],output:m.looseObject({}),examples:["allyhub sheet research/leads"]},async(e,n)=>{const o=await O(n.cwd,e.dir),s=await D(o,n.cwd,e.sheet),t=E(await b(s,"utf8")),r=await b(l(v(s),j),"utf8").catch(()=>{}),f=r===void 0?{columns:{}}:A(r).spec,c=_(t.data,f),h=I(o,s),a=Math.min(24,Math.max(4,...c.map(i=>i.name.length)));return{value:{file:h,rows:t.data.rows.length,columns:c,problems:t.problems.length},text:[`${h}: ${d(t.data.rows.length)} rows, ${String(c.length)} columns; each column's ${String(P)} most frequent values`,"",...c.flatMap(i=>R(i,a)),...t.problems.length>0?["",`The file has ${String(t.problems.length)} problems: allyhub check lists them.`]:[]].join(`
-`)}}),sheetImport=F({name:"sheet import",summary:"Makes a sheet of a CSV, TSV or workbook: a CSV as it is, a TSV as CSV, a workbook a sheet per worksheet; never over a place that is taken",input:m.strictObject({file:m.string().describe("The file to make a sheet of; a workbook's columns are typed only where it types a whole column"),to:U.optional().describe("The sheet's folder, from the project's root (default the file's name); a workbook's worksheets go at <folder>-<worksheet>"),dir:C}),positional:["file"],output:m.looseObject({}),examples:["allyhub sheet import ~/Downloads/leads.xlsx --to research/leads"]},async(e,n)=>{const o=await O(n.cwd,e.dir),s=T(n.cwd,e.file),t=await b(s).catch(()=>{throw new p("not-found",`There is no file ${s}.`,{exit:w.notFound})}),r=e.to?.includes("/")?v(e.to):"";let f;try{f=await L(s,new Uint8Array(t),{...e.to===void 0?{}:{base:x(e.to)},.../\.xlsx$/iu.test(s)?{excel:await q()}:{}})}catch(a){throw new p("bad-file",a.message,{exit:w.usage})}const c=f.map(a=>r===""?a.name:`${r}/${a.name}`);for(const a of c)if(await S(l(o,a)).catch(()=>{}))throw new p("place-taken",`${a} is already there.`,{exit:w.conflict,hint:"Name another place with --to."});const h=[];for(const[a,i]of f.entries()){const $=c[a]??i.name,g=l(o,$);await M(g,{recursive:!0}),await k(l(g,u),i.csv,{flag:"wx"}),await k(l(g,j),i.spec,{flag:"wx"}),h.push({place:$,file:`${$}/${u}`,title:i.title,rows:E(i.csv).data.rows.length})}return{value:{made:h},text:h.map(a=>`Made ${a.file}: ${d(a.rows)} row${a.rows===1?"":"s"}`).join(`
-`)}});
+import{mkdir as ie,readFile as X,stat as q,writeFile as ce}from"node:fs/promises";import{basename as k,dirname as L,extname as A,join as S,relative as B,resolve as D}from"node:path";import{z as f}from"zod";import{readSheetSource as he,sheetRoot as de,workbookFiles as fe}from"@allyhub-next/build";import{ITEM_KINDS as me}from"@allyhub-next/formats";import{EXIT as $}from"@allyhub-next/protocol";import{CellError as ue,DIFF_DEFAULTS as we,FormulaCell as O,Matrix as pe,PROFILE_TOP as be,SharedFormula as $e,cellName as M,checkWorkbook as z,dataValue as _,diffWorkbooks as ge,importRows as ye,profileTable as xe,rangeName as G,readAddress as ve,readArea as ke,scenarioNames as K,shownValue as j}from"@allyhub-next/sheet";import{CAPABILITIES as Y}from"@allyhub-next/sheet/api";import{COMPARE_TOLERANCE as Se,importXlsx as Q}from"@allyhub-next/sheet/xlsx";import{CommandError as g,defineCommand as E}from"../command.js";import{projectRoot as T}from"../project.js";import{dir as C}from"../fields.js";const x=me.sheet.entries[0];export const CALC_ROWS=50,TRACE_CELLS=50;export async function findSheet(e,o,s){const t=D(o,s);for(const n of[k(t)===x?t:S(t,x),S(e,s,x),S(e,"content",s,x)])if((await q(n).catch(()=>{}))?.isFile())return n}export const sheetFolderName=(e,o)=>B(e,L(o)).replace(/^content\//u,"");export async function sheetAt(e,o,s){const t=await findSheet(e,o,s);if(t!==void 0)return t;throw new g("not-found",`There is no sheet ${s}.`,{exit:$.notFound,hint:"Name it by its folder (research/leads, a folder under content/ with or without content/) or its sheet.yaml."})}export async function sourceOfSheet(e,o){const s=de(e,L(o)),t=await he(s.root,s.dir);return{...s,source:t,files:fe(s.root,t)}}export async function openSheet(e,o,s,t){const n=await sheetAt(e,o,s),{source:a,files:r}=await sourceOfSheet(e,n),{workbook:c,calc:i,problems:l}=z(r,{scenario:t});if(!c||!i)throw new g("bad-file",`${B(e,n)} cannot be read: ${l.map(m=>`${m.line===void 0?"":`line ${String(m.line)}: `}${m.message}`).join("; ")}`,{exit:$.usage,hint:"allyhub check lists what is wrong."});return{file:B(e,n),workbook:c,calc:i,problems:l.length+a.problems.length}}function je(e,o){const s=K(e);if(!s.includes(o))throw new g("not-found",`There is no scenario ${o}.`,{exit:$.notFound,hint:s.length>0?`It has ${s.join(", ")}.`:"sheet.yaml's scenarios holds none."})}const u=e=>e.toLocaleString("en-US"),R=e=>e.toLocaleString("en-US",{maximumFractionDigits:4}),P=e=>e>0?["",`The workbook has ${String(e)} problem${e===1?"":"s"}: allyhub check lists them.`]:[];function Ee(e,o){const s=[`${u(e.empty)} empty`,`${u(e.distinct)} distinct`];e.errors>0&&s.push(`${u(e.errors)} errors`),e.min!==void 0&&e.max!==void 0&&s.push(`${R(e.min)} to ${R(e.max)}`),e.sum!==void 0&&s.push(`sum ${R(e.sum)}`),e.mean!==void 0&&s.push(`mean ${R(e.mean)}`),e.shortest!==void 0&&e.longest!==void 0&&s.push(`${String(e.shortest)} to ${String(e.longest)} characters`);const t=[`${e.name.padEnd(o)}  ${s.join(", ")}`];return e.formula!==void 0&&t.push(`${"".padEnd(o)}  ${e.formula}`),e.top.some(n=>n.count>1)&&t.push(`${"".padEnd(o)}  most: ${e.top.map(n=>`${JSON.stringify(n.value.length>40?`${n.value.slice(0,39)}…`:n.value)} ${u(n.count)}`).join(", ")}`),t}export const sheet=E({name:"sheet",summary:"Each table of a sheet measured: its columns' counts, empty, distinct, ranges and frequent values",input:f.strictObject({sheet:f.string().describe("The sheet, by its folder or its sheet.yaml"),dir:C}),positional:["sheet"],output:f.looseObject({}),examples:["allyhub sheet research/leads"]},async(e,o)=>{const s=await T(o.cwd,e.dir),{file:t,workbook:n,calc:a,problems:r}=await openSheet(s,o.cwd,e.sheet),c=n.tables.map(l=>({name:l.name,rows:l.rows,columns:xe(a,l)})),i=c.flatMap(l=>{const m=Math.min(24,Math.max(4,...l.columns.map(w=>w.name.length)));return["",`${l.name}: ${u(l.rows)} rows, ${String(l.columns.length)} columns; each column's ${String(be)} most frequent values`,...l.columns.flatMap(w=>Ee(w,m))]});return{value:{file:t,tables:c,problems:r},text:[`${t}: ${String(n.sheets.length)} sheet${n.sheets.length===1?"":"s"}, ${String(c.length)} table${c.length===1?"":"s"}`,...i,...P(r)].join(`
+`)}});const Z=e=>{const o=e.sheets[0];if(!o)throw new g("bad-file","The workbook has no sheets.",{exit:$.usage});return o};function ee(e,o){const s=o.lastIndexOf("!");if(s<0)return{sheet:Z(e),address:o};const t=o.slice(0,s).replace(/^'|'$/gu,"").replaceAll("''","'"),n=e.sheet(t);if(!n)throw new g("not-found",`There is no sheet ${t}.`,{exit:$.notFound,hint:`It has ${e.sheets.map(a=>a.name).join(", ")}.`});return{sheet:n,address:o.slice(s+1)}}function N(e,o,s,t){const n=[];for(let a=o.top;a<=o.bottom;a++){const r=[];for(let c=o.left;c<=o.right;c++){const i=t.value(e,a,c),l=e.lookAt(a,c).format,m=e.at(a,c);r.push({address:M({row:a,col:c}),value:_(i,l),shown:j(i,l),...m instanceof O?{formula:m.text}:{}})}n.push(r)}return{sheet:e.name,what:s,area:G(o),rows:n}}function Oe(e,o,s){const t=a=>({address:"",value:_(a,void 0),shown:j(a)});if(!(s instanceof pe))return{sheet:e.name,what:o,rows:[[t(s)]]};const n=[];for(let a=0;a<s.rows;a++){const r=[];for(let c=0;c<s.cols;c++)r.push(t(s.at(a,c)));n.push(r)}return{sheet:e.name,what:o,rows:n}}function te(e,o){const{wb:s}=e;if(o===void 0)return s.sheets.flatMap(l=>{const m=l.used;return m?[N(l,m,l.name,e)]:[]});const t=s.table(o);if(t)return[N(t.sheet,t.area,o,e)];const n=s.name(o);if(n){const l=new $e(n.formula?.text??`=${o}`,0,0,{file:""}),m=Z(s);return[Oe(m,o,e.evaluate(l,m))]}const a=s.sheet(o);if(a){const l=a.used;return[l?N(a,l,o,e):{sheet:a.name,what:o,rows:[]}]}const{sheet:r,address:c}=ee(s,o),i=ke(c);if(!i)throw new g("not-found",`${o} is not a sheet, a table, a name or a range of this workbook.`,{exit:$.notFound,hint:[`Sheets: ${s.sheets.map(l=>l.name).join(", ")}.`,s.tables.length>0?`Tables: ${s.tables.map(l=>l.name).join(", ")}.`:"",s.names.size>0?`Names: ${[...s.names.values()].map(l=>l.name).join(", ")}.`:"","A range is Summary!B3:D3, or B3 on the first sheet."].filter(Boolean).join(" ")});return[N(r,i,o,e)]}function W(e){const o=[];for(const s of e)s.forEach((t,n)=>{o[n]=Math.max(o[n]??0,t.length)});return e.map(s=>s.map((t,n)=>n===s.length-1?t:t.padEnd(o[n]??0)).join("  ").trimEnd())}function Te(e,o){const s=e.area===void 0?e.what:`${e.sheet}!${e.area}`,t=e.rows.slice(0,o),n=e.area!==void 0,a=t.map(c=>[...n?[/\d+$/u.exec(c[0]?.address??"")?.[0]??""]:[],...c.map(i=>i.shown)]),r=(e.rows[0]??[]).map(c=>c.address.replace(/\d+$/u,""));return[s,...W(n?[["",...r],...a]:a),...e.rows.length>t.length?[`… ${u(e.rows.length-t.length)} more rows (--all)`]:[]]}export const sheetCalc=E({name:"sheet calc",summary:"What a sheet computes, without opening anything: a sheet, a range, a table, a name, or every sheet, as an aligned table",input:f.strictObject({sheet:f.string().describe("The sheet, by its folder or its sheet.yaml"),what:f.string().optional().describe("A sheet (its used range), a range (Summary!B3:D3, or B3 on the first sheet), a table or a name; default every sheet"),all:f.boolean().default(!1).describe(`Every row, not the first ${String(CALC_ROWS)}`),scenario:f.string().optional().describe("Compute it with this scenario's inputs (sheet.yaml's scenarios); nothing is written"),scenarios:f.boolean().default(!1).describe("Compare the base case and every scenario: what is names, cells or ranges, apart by commas, a row each; default the names no scenario sets"),dir:C}),positional:["sheet","what"],output:f.looseObject({}),examples:["allyhub sheet calc finance/budget","allyhub sheet calc finance/budget Summary","allyhub sheet calc finance/budget orders","allyhub sheet calc finance/budget 'Summary!B3:M3' --json","allyhub sheet calc finance/budget revenue --scenario high","allyhub sheet calc finance/budget 'revenue,Summary!B4' --scenarios"]},async(e,o)=>{const s=await T(o.cwd,e.dir);if(e.scenarios)return Fe(s,o.cwd,e.sheet,e.what);const{file:t,calc:n,problems:a,workbook:r}=await openSheet(s,o.cwd,e.sheet,e.scenario);e.scenario!==void 0&&je(r,e.scenario);const c=te(n,e.what),i=e.all?1/0:CALC_ROWS;return{value:{file:t,grids:c,problems:a},text:[...c.flatMap((l,m)=>[...m>0?[""]:[],...Te(l,i)]),...P(a)].join(`
+`)}});function Ce(e,o){return te(e,o.trim()).flatMap(s=>s.rows.flat().map(t=>({...t,address:t.address===""?o.trim():`${s.sheet}!${t.address}`})))}async function Fe(e,o,s,t){const n=await openSheet(e,o,s),a=K(n.workbook);if(a.length===0)throw new g("not-found",`${n.file} has no scenarios.`,{exit:$.notFound,hint:"sheet.yaml's scenarios: { high: { growth: 0.2 } } names some."});const r=new Set(a.flatMap(h=>Object.keys(n.workbook.file.scenarios?.[h]??{}).map(b=>b.toLowerCase()))),c=t?.split(",")??[...n.workbook.names.values()].map(h=>h.name).filter(h=>!r.has(h.toLowerCase()));if(c.length===0)throw new g("bad-input","Say what to compare: names, cells or ranges, apart by commas.",{exit:$.usage});const i=["Base case",...a],l=[n,...await Promise.all(a.map(h=>openSheet(e,o,s,h)))],w=c.map(h=>l.map(b=>Ce(b.calc,h))).flatMap(h=>(h[0]??[]).map((b,p)=>({output:b.address,values:Object.fromEntries(i.map((v,y)=>[v,h[y]?.[p]?.value??null])),shown:Object.fromEntries(i.map((v,y)=>[v,h[y]?.[p]?.shown??""]))})));return{value:{file:n.file,scenarios:i,outputs:w},text:[...W([["",...i],...w.map(h=>[h.output,...i.map(b=>h.shown[b]??"")])]),...P(n.problems)].join(`
+`)}}const Ae=(e,o)=>`${e.sheet===o?"":`${e.sheet.name}!`}${G({top:e.top,left:e.left,bottom:Math.min(e.bottom,Math.max(e.top,e.sheet.lastRow)),right:e.right})}`;export const sheetTrace=E({name:"sheet trace",summary:"What a cell depends on and what depends on it: its formula, where it is written, the places it reads and the cells that read it",input:f.strictObject({sheet:f.string().describe("The sheet, by its folder or its sheet.yaml"),cell:f.string().describe("The cell: Summary!B5, or B5 on the first sheet"),all:f.boolean().default(!1).describe(`Every cell that reads it, not the first ${String(TRACE_CELLS)}`),dir:C}),positional:["sheet","cell"],output:f.looseObject({}),examples:["allyhub sheet trace finance/budget 'Summary!B1'"]},async(e,o)=>{const s=await T(o.cwd,e.dir),{file:t,workbook:n,calc:a}=await openSheet(s,o.cwd,e.sheet),{sheet:r,address:c}=ee(n,e.cell),i=ve(c);if(!i)throw new g("bad-input",`${e.cell} is not a cell.`,{exit:$.usage});const{row:l,col:m}=i,w=a.value(r,l,m),h=r.lookAt(l,m).format,b=r.at(l,m),p=n.sourceOf(r,l,m),v=b instanceof O?a.precedents(b).map(d=>{const le=d.single?j(a.value(d.sheet,d.top,d.left),d.sheet.lookAt(d.top,d.left).format):`${u(d.cols)} × ${u(Math.max(0,Math.min(d.bottom,d.sheet.lastRow)-d.top+1))}`,J=d.single?d.sheet.at(d.top,d.left):void 0,H=J instanceof O?J.text:void 0;return{address:Ae(d,r),shown:le,...H===void 0?{}:{formula:H}}}):[],y=a.readers(r,l,m),I=e.all?y:y.slice(0,TRACE_CELLS),V=I.map(d=>({address:`${d.sheet===r?"":`${d.sheet.name}!`}${M(d)}`,shown:j(d.value,d.sheet.lookAt(d.row,d.col).format),formula:d.text})),U=d=>[`  ${d.address}`,d.shown,d.formula].filter(Boolean).join("  "),F=p===void 0?void 0:p.line===void 0?p.file:`${p.file}:${String(p.line)}`;return{value:{file:t,cell:`${r.name}!${M(i)}`,value:_(w,h),shown:j(w,h),...w instanceof ue?{error:w.code}:{},...b instanceof O?{formula:b.text}:{},...F===void 0?{}:{written:F},reads:v,readBy:V,readers:y.length},text:[`${r.name}!${M(i)}  ${j(w,h)}`,...b instanceof O?[`  ${b.text}`]:[],...F===void 0?[]:[`  written in ${F}`],...v.length>0?["reads:",...v.map(U)]:[],...y.length>0?[`read by ${u(y.length)}:`,...V.map(U),...y.length>I.length?[`  … ${u(y.length-I.length)} more (--all)`]:[]]:["read by nothing"]].join(`
+`)}}),sheetCapabilities=E({name:"sheet capabilities",summary:"What @allyhub/sdk/sheets holds of openpyxl's (its classes), how it differs and what it adds, and the worksheet functions, as JSON",input:f.strictObject({}),output:f.looseObject({}),examples:["allyhub sheet capabilities"]},()=>Promise.resolve({value:{...Y},text:JSON.stringify(Y,null,2)}));const se=new Set([".xlsx",".xlsm",".xltx",".xltm"]);export const DIFF_ROWS=50;const oe={value:"Value changed, formula the same",formula:"Formula changed, value the same",both:"Formula and value changed",added:"Added",removed:"Removed"},Me=e=>{const o=(e.now??e.was)?.cell??"",s=e.table===void 0?o:`${e.table}[${e.key??o}]`,t=e.column===void 0?"":` ${e.column}`;return`${e.sheet}!${s}${t}`},Re=e=>{const o=e.was?.formula??"",s=e.now?.formula??"";return[Me(e),e.was?.shown??"","→",e.now?.shown??"",e.kind==="value"?s:e.kind==="formula"||e.kind==="both"?`${o} → ${s}`:s===""?o:s]};function Ne(e,o){const s=[];for(const t of e.sheets)s.push(`Sheet ${t.name} ${t.added?"added":"removed"}`);for(const t of e.tables){const n=[t.rowsAdded.length>0?`rows added: ${t.rowsAdded.slice(0,20).join(", ")}`:"",t.rowsRemoved.length>0?`rows removed: ${t.rowsRemoved.slice(0,20).join(", ")}`:"",t.columnsAdded.length>0?`columns added: ${t.columnsAdded.join(", ")}`:"",t.columnsRemoved.length>0?`columns removed: ${t.columnsRemoved.join(", ")}`:""].filter(Boolean);s.push(`Table ${t.name}, rows lined up by ${t.by==="key"?t.key??"its key":"their place"}${n.length>0?`: ${n.join("; ")}`:""}`)}for(const t of e.names)s.push(`Name ${t.name}: ${t.was??"(none)"} → ${t.now??"(none)"}`);for(const t of e.charts)s.push(`Charts of ${t} changed`);for(const t of Object.keys(oe)){const n=e.cells.filter(r=>r.kind===t);if(n.length===0)continue;const a=o?n:n.slice(0,DIFF_ROWS);s.push("",`${oe[t]}: ${u(n.length)}`,...W(a.map(Re)).map(r=>`  ${r}`),...n.length>a.length?[`  … ${u(n.length-a.length)} more (--all)`]:[])}return s}async function ne(e,o,s){const t=D(o,s);if(se.has(A(t).toLowerCase())){const r=await X(t).catch(()=>{throw new g("not-found",`There is no file ${t}.`,{exit:$.notFound})}),c=Q(new Uint8Array(r),{name:k(t,A(t))}),{calc:i}=z({text:c.files.get(x)??"",read:l=>c.files.get(l)});if(!i)throw new g("bad-file",`${s} cannot be read.`,{exit:$.usage});return{calc:i,file:s}}const{calc:n,file:a}=await openSheet(e,o,s);return{calc:n,file:a}}export const sheetDiff=E({name:"sheet diff",summary:"Two versions of a workbook compared, by value and by formula: two folders, or a folder and an .xlsx. Cells whose formula changed and value did not are apart from those whose value changed; rows of a table line up by its key, else by their place",input:f.strictObject({was:f.string().describe("The version before: a sheet's folder or an .xlsx"),now:f.string().describe("The version after: a sheet's folder or an .xlsx"),tolerance:f.number().min(0).default(we.tolerance).describe("How far apart two numbers may be, as a share of the larger, and be the same"),all:f.boolean().default(!1).describe(`Every cell, not the first ${String(DIFF_ROWS)} of each kind`),dir:C}),positional:["was","now"],output:f.looseObject({}),examples:["allyhub sheet diff finance/budget finance/budget-v2","allyhub sheet diff finance/budget ~/Downloads/budget.xlsx --json"]},async(e,o)=>{const s=await T(o.cwd,e.dir),t=await ne(s,o.cwd,e.was),n=await ne(s,o.cwd,e.now),a=ge(t.calc,n.calc,{tolerance:e.tolerance}),{counts:r}=a,c=a.cells.length;return{value:{was:t.file,now:n.file,...a},text:[`${t.file} → ${n.file}: ${u(c)} cell${c===1?"":"s"} differ (${u(r.value)} value, ${u(r.formula)} formula, ${u(r.both)} both, ${u(r.added)} added, ${u(r.removed)} removed)`,...Ne(a,e.all)].join(`
+`)}});const Ie=f.string().transform(e=>e.replace(/^\/+|\/+$/gu,"")).refine(e=>e!==""&&!e.split("/").some(o=>o===""||o==="."||o===".."),{message:"a folder from the project's root, such as research/leads"});export const IMPORT_DIFFERENCES=50;const ae=e=>e===null?"empty":typeof e=="string"?JSON.stringify(e):String(e);function Le(e,o){const{formulas:s,same:t,uncached:n,moving:a,differences:r}=e,c=[`${u(t)} of ${u(s)} formulas compute what the file holds`,...a>0?[`${u(a)} read the clock or a random number, not compared`]:[],...n>0?[`${u(n)} have no value in the file`]:[]],i=o?r:r.slice(0,IMPORT_DIFFERENCES);return[`Computed here against the file: ${c.join("; ")}.`,...r.length>0?[`${u(r.length)} differ${r.length===1?"s":""}:`,...i.map(l=>`  ${l.sheet}!${l.cell}  ${l.formula}  file ${ae(l.file)}  here ${ae(l.engine)}`),...r.length>i.length?[`  … ${u(r.length-i.length)} more (--all)`]:[]]:[]]}async function re(e,o){for(const[s,t]of o){const n=S(e,s);await ie(L(n),{recursive:!0}),await ce(n,t,{flag:"wx"})}}export const sheetImport=E({name:"sheet import",summary:"Makes a sheet of an Excel, CSV or TSV file: its sheets, tables, formulas, names and looks as sheet.yaml and CSV files, said what could not be carried over, each formula computed here and compared with the value the file holds; never over a place that is taken",input:f.strictObject({file:f.string().describe("The file to make a sheet of: .xlsx, .xlsm, .csv or .tsv"),to:Ie.optional().describe("The sheet's folder, from the project's root (default the file's name)"),tolerance:f.number().min(0).default(Se).describe("How far apart a computed number and the file's may be, as a share of the larger, and count as the same; 0 lists every difference"),all:f.boolean().default(!1).describe(`Every difference, not the first ${String(IMPORT_DIFFERENCES)}`),dir:C}),positional:["file"],output:f.looseObject({}),examples:["allyhub sheet import ~/Downloads/forecast.xlsx --to finance/forecast","allyhub sheet import ~/Downloads/leads.csv --to research/leads"]},async(e,o)=>{const s=await T(o.cwd,e.dir),t=D(o.cwd,e.file),n=A(t).toLowerCase(),a=se.has(n);if(n===".xls"||n===".xlsb")throw new g("bad-file",`${k(t)} is Excel's binary format.`,{exit:$.usage,hint:"Save it as .xlsx, then import that."});if(!a&&n!==".csv"&&n!==".tsv")throw new g("bad-file",`${k(t)} is not an .xlsx, .xlsm, .csv or .tsv file.`,{exit:$.usage});const r=await X(t).catch(()=>{throw new g("not-found",`There is no file ${t}.`,{exit:$.notFound})}),c=k(t,A(t)),i=e.to??c;if(await q(S(s,i)).catch(()=>{}))throw new g("place-taken",`${i} is already there.`,{exit:$.conflict,hint:"Name another place with --to."});const l=S(s,i),m=e.to===void 0?c:k(e.to);if(a){let h;try{h=Q(new Uint8Array(r),{name:m,tolerance:e.tolerance})}catch(p){throw new g("bad-file",`${k(t)} cannot be read: ${p.message}`,{exit:$.usage})}await re(l,h.files);const b=[...h.files.keys()];return{value:{place:i,files:b.map(p=>`${i}/${p}`),sheets:h.sheets,tables:h.tables,lost:h.lost,problems:h.problems,compared:h.compared},text:[`Made ${i}/: ${b.join(", ")}`,...h.lost.length>0?["Not carried over:",...h.lost.map(p=>`  ${p}`)]:["Nothing was left out."],...Le(h.compared,e.all),...h.problems.length>0?["Problems:",...h.problems.map(p=>`  ${p.file}${p.line===void 0?"":`:${String(p.line)}`}: ${p.message}`)]:[],`allyhub sheet calc ${i}, then allyhub frames ${i}, to see it.`].join(`
+`)}}let w;try{w=ye(m,r.toString("utf8"),n===".tsv"?"	":",")}catch(h){throw new g("bad-file",h.message,{exit:$.usage})}return await re(l,new Map([[x,w.text],[w.path,w.csv]])),{value:{place:i,files:[`${i}/${x}`,`${i}/${w.path}`],rows:w.rows,lost:[]},text:`Made ${i}/${x} and ${i}/${w.path}: ${u(w.rows)} row${w.rows===1?"":"s"}`}});