@north-light/cli 0.0.0 → 0.3.413

package/dist/commands/pkg/browse/catalog.d.ts

@@ -0,0 +1,9 @@
+import { type Catalog, type PluginCapability, type PluginEntry } from './model.js';
+/** Every rail source with its rows: the installed library first, then each
+ *  registered marketplace. Called on open and after any action that could
+ *  change install state. Must never throw for a broken marketplace — record it
+ *  in `warnings` and keep the rest of the catalog. */
+export declare function loadCatalog(): Catalog;
+/** What the focused plugin adds to this machine. Resolved from `entry.root`;
+ *  null when the plugin has no directory on disk yet. */
+export declare function loadCapability(entry: PluginEntry): Promise<PluginCapability | null>;

package/dist/commands/pkg/browse/catalog.js

@@ -0,0 +1 @@
+var z=Object.defineProperty;var l=(e,n)=>z(e,"name",{value:n,configurable:!0});import{statSync as w}from"node:fs";import{isAbsolute as D,join as k}from"node:path";import{SUBTREE_NAMES as U,coreCommandPaths as B,extensibleCoreBranches as _}from"../../../build-root.js";import{discoverPluginCommandCandidates as F,validateEffectiveCommandPlugins as L,validatePluginCommands as q}from"../../../core/command-plugins/discovery.js";import{qualifiedTopLevelCommandName as C}from"../../../core/command-manifests/registry.js";import{listDirs as x,pathExists as A,walkFiles as Z}from"../../../core/fs-utils.js";import{currentSha as W,gitSync as G}from"../../../core/git.js";import{packageFiles as H}from"../../../core/graph/package-files.js";import{readMarketplaceManifest as K,readPluginManifest as E}from"../../../core/manifest.js";import{readConfig as O}from"../../../core/config.js";import{documentFields as J}from"../../../migrations/004-canvas-documents/fields.js";import{pluginMemoryDir as Q,projectScopeRoot as y}from"../../../core/scope.js";import{runtimeRoot as S}from"../../../core/layout.js";import{isGitUrl as V}from"../shared.js";import{INSTALLED_SOURCE_ID as $,marketplaceSourceId as M}from"./model.js";function I(e){const n=/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/.exec(e);return n===null?null:{core:[Number(n[1]),Number(n[2]),Number(n[3])],prerelease:n[4]?.split(".")??[]}}l(I,"parseSemver");function X(e,n){for(let r=0;r<e.core.length;r+=1){const o=e.core[r]-n.core[r];if(o!==0)return o}if(e.prerelease.length===0||n.prerelease.length===0)return e.prerelease.length===n.prerelease.length?0:e.prerelease.length===0?1:-1;for(let r=0;r<Math.max(e.prerelease.length,n.prerelease.length);r+=1){const o=e.prerelease[r],a=n.prerelease[r];if(o===void 0||a===void 0)return o===void 0?-1:1;const i=/^\d+$/.test(o),t=/^\d+$/.test(a);if(i&&t){const s=Number(o)-Number(a);if(s!==0)return s}else{if(i!==t)return i?-1:1;if(o!==a)return o<a?-1:1}}return 0}l(X,"compareSemver");function P(e,n){if(e===void 0||n===void 0)return!1;const r=I(e),o=I(n);return r!==null&&o!==null&&X(o,r)>0}l(P,"offeredVersionIsNewer");function Y(e){return e.startsWith("./")||e.startsWith("../")||!D(e)&&!V(e)}l(Y,"isMarketplaceRelativeSource");function j(e,n){return{kind:"installed",scope:e.scope,enabled:e.enabled,version:e.version,path:e.root,updateAvailable:P(e.version,n)}}l(j,"pluginInstallState");function ee(e,n){return{key:`${$}:${e.scope}:${e.name}`,name:e.name,ref:e.name,sourceId:$,...e.sourceMarketplace!==void 0?{marketplace:e.sourceMarketplace}:{},...n===void 0?{}:{version:n},description:e.manifest.description,keywords:[],owner:e.manifest.owner,source:e.manifest.source,install:j(e,n),root:e.root}}l(ee,"installedEntry");function v(e,n){return`${e}:${n}`}l(v,"marketplacePluginKey");function ne(e,n){const r=W(e.root)??void 0,o=G(["show","-s","--format=%cI","HEAD"],e.root),a=o.status===0&&o.stdout.trim()||void 0,i=e.manifest.plugins;return{name:e.name,scope:e.scope,url:e.url,ref:e.ref,path:e.root,owner:e.manifest.owner,version:e.manifest.version,pluginCount:i.length,installedCount:i.filter(t=>n.has(v(e.name,t.name))).length,updatableCount:i.filter(t=>{const s=n.get(v(e.name,t.name));return s!==void 0&&P(s.version,t.version)}).length,revision:r,revisionDate:a}}l(ne,"marketplaceDetail");function te(e,n,r){const o=r.get(v(e.name,n.name)),a=Y(n.source)?k(e.root,n.source):void 0;return{key:`${M(e.name,e.scope)}:${n.name}`,name:n.name,ref:`${e.name}/${n.name}`,sourceId:M(e.name,e.scope),marketplace:e.name,version:n.version,description:n.description,keywords:n.keywords??[],owner:e.manifest.owner,source:n.source,install:o===void 0?{kind:"absent"}:j(o,n.version),...o!==void 0?{root:o.root}:a!==void 0&&A(a)?{root:a}:{}}}l(te,"marketplaceEntry");function N(e,n){try{return O(e)}catch(r){return n.push(`Could not read ${e} config: ${b(r)}`),null}}l(N,"readableConfig");function re(e){const n=[...y()===null?[]:[{scope:"project",root:y()}],{scope:"user",root:S()}],r=[];for(const{scope:o,root:a}of n){const i=N(o,e);for(const t of x(k(a,"plugins"))){const s=k(a,"plugins",t);try{const c=E(s);if(c===null){e.push(`Plugin "${t}" has no readable manifest: ${s}`);continue}const u=i?.plugins[t];r.push({name:t,scope:o,root:s,manifest:c,enabled:typeof u?.enabled=="boolean"?u.enabled:!0,sourceMarketplace:typeof u?.source_marketplace=="string"?u.source_marketplace:void 0,version:typeof u?.version=="string"?u.version:c.version})}catch(c){e.push(`Could not read plugin "${t}": ${b(c)}`)}}}return r}l(re,"readInstalledPlugins");function oe(e,n,r){if(!Array.isArray(e))return r.push(`Marketplace "${n}" has an invalid plugins list.`),[];const o=[];for(const[a,i]of e.entries()){if(typeof i!="object"||i===null||Array.isArray(i)){r.push(`Marketplace "${n}" has an invalid plugin entry at index ${a}.`);continue}const t=i;if(typeof t.name!="string"||t.name===""||typeof t.source!="string"||t.source===""){r.push(`Marketplace "${n}" has a plugin entry without a name and source at index ${a}.`);continue}o.push({name:t.name,source:t.source,...typeof t.version=="string"?{version:t.version}:{},...typeof t.description=="string"?{description:t.description}:{},...Array.isArray(t.keywords)&&t.keywords.every(s=>typeof s=="string")?{keywords:t.keywords}:{}})}return o}l(oe,"marketplaceEntries");function se(e,n,r){if(typeof e!="object"||e===null||Array.isArray(e))return r.push(`Marketplace "${n}" has an invalid manifest.`),null;const o=e;if(typeof o.name!="string"||o.name==="")return r.push(`Marketplace "${n}" has a manifest without a name.`),null;const a=o.owner,i=typeof a=="object"&&a!==null&&!Array.isArray(a)?{...typeof a.name=="string"?{name:a.name}:{},...typeof a.email=="string"?{email:a.email}:{}}:void 0;return{name:o.name,plugins:oe(o.plugins,o.name,r),...typeof o.version=="string"?{version:o.version}:{},...i!==void 0?{owner:i}:{}}}l(se,"readableMarketplaceManifest");function ae(e){const n=[...y()===null?[]:[{scope:"project",root:y()}],{scope:"user",root:S()}],r=[];for(const{scope:o,root:a}of n){const i=N(o,e);for(const t of x(k(a,"marketplaces"))){const s=k(a,"marketplaces",t);try{const c=K(s);if(c===null){e.push(`Marketplace "${t}" has no readable manifest: ${s}`);continue}const u=se(c,t,e);if(u===null)continue;const d=i?.marketplaces[t];r.push({name:t,scope:o,root:s,manifest:u,url:d?.url??"",ref:d?.ref??"main"})}catch(c){e.push(`Could not read marketplace "${t}": ${b(c)}`)}}}return r}l(ae,"readMarketplaces");function xe(){const e=[],n=re(e),r=ae(e),o=new Map(n.filter(t=>t.sourceMarketplace!==void 0).map(t=>[v(t.sourceMarketplace,t.name),t])),a=new Map(r.flatMap(t=>t.manifest.plugins.map(s=>[v(t.name,s.name),s.version]))),i=[{id:$,kind:"installed",label:"Installed",entries:n.map(t=>ee(t,t.sourceMarketplace===void 0?void 0:a.get(v(t.sourceMarketplace,t.name)))).sort((t,s)=>t.name.localeCompare(s.name))}];for(const t of r.sort((s,c)=>s.name.localeCompare(c.name)))try{i.push({id:M(t.name,t.scope),kind:"marketplace",label:t.name,marketplace:ne(t,o),entries:t.manifest.plugins.map(s=>te(t,s,o)).sort((s,c)=>s.name.localeCompare(c.name))})}catch(s){e.push(`Could not load marketplace "${t.name}": ${b(s)}`)}return{sources:i,installScopes:["user",...y()===null?[]:["project"]],warnings:e}}l(xe,"loadCatalog");function R(e,n=[]){const r=[...n,e.name];return e.kind==="branch"?{path:r,kind:"branch",description:e.description,whenToUse:e.whenToUse,summary:e.summary,...e.tier!==void 0?{tier:e.tier}:{},...e.passthrough!==void 0?{passthrough:e.passthrough}:{},...e.rootEntry!==void 0?{rootEntry:e.rootEntry}:{},children:e.children.map(o=>R(o,r)),params:[],output:[],effects:[]}:{path:r,kind:"leaf",description:e.description,whenToUse:e.whenToUse,summary:e.summary,...e.tier!==void 0?{tier:e.tier}:{},children:[],params:e.params,output:e.output,effects:[...e.effects],..."rest"in e?{rest:{method:e.rest.method,path:e.rest.path,streaming:e.rest.streaming===!0}}:{}}}l(R,"commandNode");function ie(e){return H(Q(e)).files.map(n=>{const r=J(n.frontmatter,n.body,{missingPrivacy:"public"});let o;try{o=w(n.path).size}catch{}return{name:`${e.name}/${n.name}`,kind:r.kind==="preference"?"preference":"knowledge",...r.summary!==null?{shortForm:r.summary}:{},...r.preview!==""?{routingLine:r.preview}:{},path:n.path,...o!==void 0?{sizeBytes:o}:{},rules:r.rules,unlisted:r.unlisted,...r.whyItExists!==null?{rationale:r.whyItExists}:{},body:n.body}})}l(ie,"docDetails");function le(e){try{return Z(e).reduce((n,r)=>n+w(r).size,0)}catch{return}}l(le,"directorySize");async function Ae(e){if(e.root===void 0||!A(e.root))return null;try{const n=E(e.root);if(n===null)return null;const r=e.install.kind==="installed"?e.install.scope:"user",o={name:e.name,scope:r,root:e.root,manifest:n,enabled:e.install.kind!=="installed"||e.install.enabled},a=new Set(U),[i,t]=await Promise.all([B(),_()]);let s=q(o,a,i,t);const c=[];if(e.install.kind==="installed"&&e.install.enabled)try{s=L(a,void 0,void 0,i,t).find(p=>p.plugin.root===e.root)??s}catch(d){c.push({message:`Could not resolve the effective command registry: ${b(d)}`,next:"Repair the unreadable installed plugin manifest, then reopen the dossier."})}if(e.install.kind!=="installed"||!e.install.enabled){const d=new Map;for(const m of F())if(m.plugin.root!==e.root)for(const f of m.contributions){const h=d.get(f.node.name)??[];h.push(m.plugin),d.set(f.node.name,h)}const p=e.install.kind==="installed"?"enabling":"installing";s.contributions=s.contributions.map(m=>{const f=d.get(m.node.name);if(f===void 0||f.length===0)return m;const h=C({name:e.name,sourceMarketplace:e.marketplace},m.node.name),T=f.map(g=>`moves ${g.name}'s to "${C(g,m.node.name)}"`);return s.issues.push({code:"command_collision",plugin:o.name,path:m.node.name,message:`top-level command "${m.node.name}" is already claimed by ${f.map(g=>g.name).join(", ")} \u2014 ${p} mounts this one as "${h}" and ${T.join(" and ")}`,received:[...f.map(g=>g.name),o.name].join(", "),expected:"an origin-qualified top-level command for each claimant",next:`After ${p}, invoke "${h}".`}),{...m,node:{...m.node,name:h}}})}const u=n.transport;return{root:e.root,transport:u?.kind??null,...u?.kind==="exec"&&u.executable!==void 0?{transportTarget:u.executable}:{},...u?.kind==="http"?{transportTarget:u.endpoint}:{},commands:s.contributions.map(d=>R(d.node)),commandIssues:[...s.issues.map(({message:d,next:p})=>({message:d,...p!==void 0?{next:p}:{}})),...c],docs:ie(o),sizeBytes:le(e.root)}}catch{return null}}l(Ae,"loadCapability");function b(e){return e instanceof Error?e.message:String(e)}l(b,"errorMessage");export{Ae as loadCapability,xe as loadCatalog};

package/dist/commands/pkg/browse/command-view.d.ts

@@ -0,0 +1,3 @@
+import type { CommandNode, PluginCapability } from './model.js';
+/** Every line of one command's contract view, wrapped to `width`. */
+export declare function renderCommandView(node: CommandNode, capability: PluginCapability, width: number): string[];

package/dist/commands/pkg/browse/command-view.js

@@ -0,0 +1 @@
+var N=Object.defineProperty;var u=(e,s)=>N(e,"name",{value:s,configurable:!0});import{visibleWidth as g,wrapTextWithAnsi as b}from"@earendil-works/pi-tui";import{theme as f,wrapText as x}from"../../../core/tui/panel.js";import{commandLabel as h}from"./model.js";function k(e,s,t){const n=[];return n.push(...a(h(e),t).map(r=>f.fg("accent",f.bold(r)))),n.push(...a(`${e.kind.toUpperCase()} COMMAND \xB7 ${(e.tier??"normal").toUpperCase()} TIER`,t).map(r=>f.fg("dim",r))),n.push(""),n.push(...p(e.description,t)),c(n,"WHEN TO USE",t),n.push(...p(e.whenToUse,t)),c(n,"SUMMARY",t),n.push(...p(e.summary,t)),e.kind==="leaf"?v(n,e,s,t):S(n,e,t),n}u(k,"renderCommandView");function v(e,s,t,n){if(c(e,"PARAMS",n),s.params.length===0)e.push(...p("No input parameters.",n));else for(const o of s.params)e.push(...M(o,n));if(c(e,"OUTPUT",n),s.output.length===0)e.push(...p("No output fields declared.",n));else for(const o of s.output)e.push(...m(o,n));if(c(e,"EFFECTS",n),s.effects.length===0)e.push(...p("No effects declared.",n));else for(const o of s.effects)e.push(...i("  \u2022 ",o,n));if(c(e,"INVOKED VIA",n),t.transport===null){e.push(...a("This plugin declares no command transport.",n).map(o=>f.fg("warning",o)));return}const r=t.transportTarget??"No target declared.";e.push(...i(`  ${t.transport}  `,r,n)),t.transport==="http"&&s.rest!==void 0&&e.push(...i("  REST  ",`${s.rest.method} ${s.rest.path} \xB7 ${s.rest.streaming?"streaming response":"single response"}`,n))}u(v,"renderLeaf");function S(e,s,t){if(s.rootEntry!==void 0&&(c(e,"ROOT ENTRY",t),e.push(...i("  Concept  ",s.rootEntry.concept,t)),e.push(...i("  Description  ",s.rootEntry.description,t)),e.push(...i("  When to use  ",s.rootEntry.whenToUse,t))),s.passthrough!==void 0&&(c(e,"PASSES THROUGH",t),e.push(...i("  Binary  ",s.passthrough.bin,t)),e.push(...i("  Install  ",s.passthrough.installHint,t))),c(e,"CHILDREN",t),s.children.length===0){e.push(...p(s.passthrough===void 0?"No subcommands.":"No subcommands \u2014 every argument is forwarded to the binary.",t));return}for(const n of s.children)e.push(...i(`  ${h(n)}  `,n.description,t))}u(S,"renderBranch");function M(e,s){const t=D(e),n=i(`  ${t}  `,O(e),s),r=C;return e.kind==="positional"?(e.repeatable===!0&&n.push(...i(r,"Repeatable; supply multiple values in argv order.",s)),e.encoding!==void 0&&n.push(...i(r,d(e.encoding),s)),e.defaultFromEnv!==void 0&&n.push(...i(r,E(e.defaultFromEnv),s))):e.kind==="flag"?(e.choices!==void 0&&n.push(...i(r,`Choices: ${e.choices.join(", ")}.`,s)),e.default!==void 0&&n.push(...i(r,`Default: ${R(e.default)}.`,s)),e.repeatable===!0&&n.push(...i(r,"Repeatable; supply the flag multiple times to accumulate values.",s)),e.encoding!==void 0&&n.push(...i(r,d(e.encoding),s)),e.defaultFromEnv!==void 0&&n.push(...i(r,E(e.defaultFromEnv),s)),e.hidden===!0&&n.push(...i(r,"Hidden from the command's ordinary -h output.",s,"warning"))):e.kind==="context-file"&&(n.push(...i(r,`Mapped input: ${e.name}.`,s)),e.shape!==void 0&&n.push(...i(r,`Expected JSON: ${e.shape}`,s))),n.push(...i(r,`Constraint: ${e.constraint}`,s)),n}u(M,"renderParam");function m(e,s,t="  "){const n=`${t}  `,r=[...i(`${t}${e.name}  `,`${e.type} \xB7 ${e.required?"required":"optional"}`,s),...i(n,`Constraint: ${e.constraint}`,s)];return r.push(...$(e,s,n)),r}u(m,"renderField");function $(e,s,t){const n=[];e.values!==void 0&&n.push(...i(t,`Values: ${e.values.join(", ")}.`,s));for(const r of e.children??[])n.push(...m(r,s,t));if(e.items!==void 0){const r=e.items,o=r.constraint.length>0?` \xB7 ${r.constraint}`:"";n.push(...i(t,`Each element: ${r.type}${o}`,s)),n.push(...$(r,s,`${t}  `))}return n}u($,"renderShapeBody");const C="    ";function D(e){switch(e.kind){case"positional":return`${e.name}${e.repeatable===!0?"\u2026":""}`;case"flag":return`--${e.name}`;case"stdin":return e.name;case"context-file":return"--context-file PATH"}}u(D,"paramLabel");function O(e){const s=e.required?"required":"optional";switch(e.kind){case"positional":return`positional \xB7 ${e.type??"string"} \xB7 ${s}`;case"flag":return`flag \xB7 ${e.type} \xB7 ${s}`;case"stdin":return`stdin \xB7 raw text \xB7 ${s}`;case"context-file":return`context file \xB7 JSON file \xB7 ${s}`}}u(O,"paramMeta");function d(e){return e==="base64"?"Encoding: reads the local file's raw bytes and sends base64; the path itself is never sent.":"Encoding: reads the local file as UTF-8 text and sends its content; the path itself is never sent."}u(d,"encodingDetail");function R(e){return typeof e=="string"?JSON.stringify(e):String(e)}u(R,"formatValue");function E(e){return`When $${e} is set and non-empty, it supplies the value and counts as supplied.`}u(E,"envDefaultDetail");function c(e,s,t){e.push(""),e.push(...a(s,t).map(n=>f.fg("dim",n)))}u(c,"section");function p(e,s){return a(e,Math.max(1,s-2)).map(n=>`  ${f.fg("dim",n)}`)}u(p,"paragraph");function i(e,s,t,n="dim"){const r=g(e);if(r>=t)return[...a(e.trimEnd(),t).map(l=>f.fg("accent",l)),...a(s,Math.max(1,t-2)).map(l=>`  ${f.fg(n,l)}`)];const o=Math.max(1,t-r),T=" ".repeat(r);return a(s,o).map((l,y)=>y===0?`${f.fg("accent",e)}${f.fg(n,l)}`:`${T}${f.fg(n,l)}`)}u(i,"hanging");function a(e,s){const t=e.trim(),n=Math.max(1,s);return t.split(/\s+/).some(r=>g(r)>n)?b(t,n):x(t,n)}u(a,"wrapped");export{k as renderCommandView};

package/dist/commands/pkg/browse/detail-panel.d.ts

@@ -0,0 +1,66 @@
+import type { ActionOutcome, CatalogSource, PluginCapability, PluginEntry } from './model.js';
+export declare class PkgDetailPanel {
+    private entry;
+    private source;
+    private capability;
+    private pluginAction;
+    private marketplaceAction;
+    /** Page-level catalog problems. The list's notice shows the first; this is
+     *  where the rest stay readable. */
+    private warnings;
+    private scroll;
+    /** Extra scrolling the user asked for past the last selectable row, so the
+     *  inert tail of the overview stays reachable. Reset whenever the cursor
+     *  moves or the view changes. */
+    private tailScroll;
+    private cursor;
+    private view;
+    /** Command branches the user has folded shut, by command path. Branches are
+     *  open by default: the explorer's whole point is that nothing is hidden. */
+    private collapsed;
+    /** Last render's geometry, so scrolling can clamp against real content
+     *  instead of running a counter nobody can see. */
+    private lastLines;
+    private lastHeight;
+    /** Where the cursor's row sits in the last built overview, in line numbers. */
+    private cursorRange;
+    setEntry(entry: PluginEntry | undefined, source: CatalogSource | undefined, capability: PluginCapability | null | undefined): void;
+    setPluginAction(entry: PluginEntry | undefined, outcome: ActionOutcome): void;
+    setMarketplaceAction(sourceId: string | undefined, outcome: ActionOutcome): void;
+    setWarnings(warnings: string[]): void;
+    /** True while an opened doc or command owns the pane, so the shell's footer
+     *  can teach `esc back` instead of `esc list`. */
+    get viewing(): boolean;
+    /** `j`/`k`: move the cursor between selectable rows on the overview, scroll a
+     *  line inside an opened view — and scroll the overview too when the plugin
+     *  has nothing selectable to move between. */
+    moveVertical(delta: number): void;
+    /** `space`: fold the focused command branch shut, or open it again. */
+    toggleExpand(): boolean;
+    /** `enter`/`l`: open the focused doc or command as its own view. */
+    open(): boolean;
+    /** `h`/`left`: pop an open view, else fold the focused branch. False means
+     *  the key was not used here and the shell should leave for the list. */
+    collapseOrPop(): boolean;
+    /** `esc`: pop an open view. False at the root, where the shell leaves. */
+    escape(): boolean;
+    private popView;
+    private toggleExpandShut;
+    /** Command rows in display order, skipping the children of folded branches. */
+    private commandRows;
+    /** Every row the cursor can land on, in the order the overview renders them.
+     *  The renderer walks the same two lists, so index N here is row N there. */
+    private targets;
+    render(width: number, height: number, focused: boolean): string[];
+    private lines;
+    private overviewLines;
+    private commandRowLines;
+    private status;
+    private transportLine;
+    private fromLines;
+    /** The dossier for a source rather than a plugin: what a marketplace is and
+     *  where it came from, or the library's own shape — plus every catalog
+     *  problem, which is page-level and has no other home with room for it. */
+    private sourceLines;
+    private size;
+}

package/dist/commands/pkg/browse/detail-panel.js

@@ -0,0 +1 @@
+var M=Object.defineProperty;var f=(c,i)=>M(c,"name",{value:i,configurable:!0});import{truncateToWidth as L,visibleWidth as p}from"@earendil-works/pi-tui";import{padAnsi as S,theme as t,wrapText as v}from"../../../core/tui/panel.js";import{renderCommandView as R}from"./command-view.js";import{renderDocView as x}from"./doc-view.js";import{commandLabel as T,displayVersion as C,plural as w}from"./model.js";function A(c,i,e,n,s){const o=`${c}${t.fg("accent",i)}`;if(e===void 0||e.trim()==="")return[o];const r=`${c}${i} \u2014 ${e}`;if(p(r)<=n)return[`${o}${t.fg("dim",` \u2014 ${e}`)}`];const a=s??" ".repeat(p(c)+2);return[o,...v(e,Math.max(1,n-a.length)).map(u=>`${a}${t.fg("dim",u)}`)]}f(A,"entryLines");function m(c,i,e,n=c){return v(i,Math.max(1,e-c.length)).map((s,o)=>`${o===0?c:n}${s}`)}f(m,"indented");class N{static{f(this,"PkgDetailPanel")}entry;source;capability;pluginAction;marketplaceAction;warnings=[];scroll=0;tailScroll=0;cursor=0;view={kind:"overview"};collapsed=new Set;lastLines=0;lastHeight=1;cursorRange;setEntry(i,e,n){const s=this.entry?.key!==i?.key;(s||this.source?.id!==e?.id)&&(this.scroll=0,this.tailScroll=0),s&&(this.pluginAction=void 0,this.view={kind:"overview"},this.cursor=0,this.collapsed.clear()),this.source?.id!==e?.id&&(this.marketplaceAction=void 0),this.entry=i,this.source=e,this.capability=n}setPluginAction(i,e){this.pluginAction=i===void 0?void 0:{key:i.key,outcome:e}}setMarketplaceAction(i,e){this.marketplaceAction=i===void 0?void 0:{sourceId:i,outcome:e}}setWarnings(i){this.warnings=i}get viewing(){return this.view.kind!=="overview"}moveVertical(i){const e=this.targets();if(this.view.kind!=="overview"||e.length===0){this.scroll=Math.max(0,Math.min(this.scroll+i,Math.max(0,this.lastLines-this.lastHeight)));return}const n=Math.max(0,Math.min(e.length-1,this.cursor+i));if(n!==this.cursor){this.cursor=n,this.tailScroll=0;return}this.tailScroll=Math.max(0,this.tailScroll+i)}toggleExpand(){const i=this.targets()[this.cursor];if(this.view.kind!=="overview"||i?.kind!=="command"||i.node.children.length===0)return!1;const e=i.node.path.join(" ");return this.collapsed.has(e)?this.collapsed.delete(e):this.collapsed.add(e),!0}open(){if(this.view.kind!=="overview")return!1;const i=this.targets()[this.cursor];return i===void 0?!1:(this.view=i.kind==="command"?{kind:"command",node:i.node}:{kind:"doc",doc:i.doc},this.scroll=0,!0)}collapseOrPop(){return this.view.kind!=="overview"?this.popView():this.toggleExpandShut()}escape(){return this.popView()}popView(){return this.view.kind==="overview"?!1:(this.view={kind:"overview"},this.scroll=0,this.tailScroll=0,!0)}toggleExpandShut(){const i=this.targets()[this.cursor];if(i?.kind!=="command"||i.node.children.length===0)return!1;const e=i.node.path.join(" ");return this.collapsed.has(e)?!1:(this.collapsed.add(e),!0)}commandRows(){const i=[],e=f((n,s)=>{for(const o of n)i.push({node:o,depth:s}),o.children.length>0&&!this.collapsed.has(o.path.join(" "))&&e(o.children,s+1)},"walk");return e(this.capability?.commands??[],0),i}targets(){const i=this.capability;return i==null?[]:[...this.commandRows().map(e=>({kind:"command",node:e.node})),...i.docs.map(e=>({kind:"doc",doc:e}))]}render(i,e,n){const s=this.lines(i,n);this.lastLines=s.length,this.lastHeight=e;let o=0;if(n){const a=this.view.kind==="overview"?this.cursorRange:void 0;let u;a!==void 0&&(a.start<this.scroll&&(this.scroll=a.start),a.start+a.count>this.scroll+e&&(this.scroll=a.start+a.count-e),u=this.scroll,this.scroll+=this.tailScroll),this.scroll=Math.max(0,Math.min(this.scroll,Math.max(0,s.length-e))),u!==void 0&&(this.tailScroll=Math.max(0,this.scroll-u)),o=this.scroll}const r=s.slice(o,o+e).map(a=>L(a,i));for(;r.length<e;)r.push("");return r}lines(i,e){const n=this.entry;return n===void 0?this.sourceLines(this.source,i):this.view.kind==="doc"?x(this.view.doc,i):this.view.kind==="command"&&this.capability!==void 0&&this.capability!==null?R(this.view.node,this.capability,i):this.overviewLines(n,i,e)}overviewLines(i,e,n){const s=[],o=[],r=f((l,$=!1)=>{$&&o.push({start:s.length,count:l.length}),s.push(...l)},"push"),a=C(i)??"",u=t.fg("accent",t.bold(i.name)),k=e-p(u)-p(a);r([k>=2?`${u}${" ".repeat(k)}${t.fg("dim",a)}`:u]),r([this.status(i)]),i.description&&(r([""]),r(v(i.description,e)));const d=this.capability;if(d===void 0)r(["",t.fg("dim","ADDS TO CRTR"),t.fg("dim"," Reading capability surface\u2026")]);else if(d===null)r(["",t.fg("warning","Capability details are unavailable \u2014 plugin files are not on disk.")]);else{r(["",t.fg("dim","ADDS TO CRTR")]);const l=this.transportLine(d);l!==void 0&&r([l]),r([` ${w(this.commandRows().length,"command","commands")} \xB7 ${w(d.docs.length,"document","documents")}`].map(h=>t.fg("dim",h)));const $=this.commandRows();if($.length>0||d.commandIssues.length>0){r(["",t.fg("dim","COMMANDS")]);for(const h of $)r(this.commandRowLines(h,e),!0);for(const h of d.commandIssues)r(m(" ! ",`${h.message}${h.next?` \u2014 ${h.next}`:""}`,e,"   ").map(b=>t.fg("warning",b)))}if(d.docs.length>0){r(["",t.fg("dim","DOCUMENTS")]);for(const h of d.docs)r(A("   ",h.name,h.shortForm,e),!0)}i.install.kind==="installed"&&d.sizeBytes!==void 0&&(r(["",t.fg("dim","ON DISK")]),r([` ${t.fg("accent",i.install.path)}${t.fg("dim",` \xB7 ${this.size(d.sizeBytes)}`)}`]))}if(r(this.fromLines(i,e)),this.pluginAction?.key===i.key&&this.pluginAction.outcome.detail?.length){r(["",t.fg("dim","LAST ACTION")]);for(const l of this.pluginAction.outcome.detail)r(m(" ",l,e))}this.cursor=o.length===0?0:Math.min(this.cursor,o.length-1),this.cursorRange=o[this.cursor];const g=this.cursorRange;if(n&&g!==void 0)for(let l=g.start;l<g.start+g.count;l+=1)s[l]=t.bg("selectedBg",S(s[l]??"",e));return s}commandRowLines(i,e){const n=`   ${"  ".repeat(i.depth)}`,s=i.node.children.length===0?"  ":this.collapsed.has(i.node.path.join(" "))?`${t.fg("dim","\u25B8")} `:`${t.fg("dim","\u25BE")} `,o=`${n}${s}`,r=i.node.children.length===0?void 0:" ".repeat(p(o));return A(o,T(i.node),i.node.description,e,r)}status(i){if(i.install.kind==="absent")return t.fg("dim","Not installed");if(i.install.scope==="builtin")return`${t.fg("muted","Builtin")} \xB7 ships with crtr`;const e=i.install.enabled?t.fg("success","enabled"):t.fg("dim","disabled");return i.install.updateAvailable?`${t.fg("warning",`Update available \xB7 ${i.install.version??"?"} \u2192 ${i.version??"?"}`)} \xB7 ${e}`:`Installed \xB7 ${i.install.scope} \xB7 ${e}`}transportLine(i){if(i.transport===null)return;const e=i.transportTarget===void 0?"":` \xB7 ${i.transportTarget}`;return i.transport==="http"?` ${t.fg("accent","Transport")}  http${t.fg("warning",e)}`:` ${t.fg("accent","Transport")}  exec${t.fg("dim",e)}`}fromLines(i,e){if(!i.marketplace&&!i.source&&!i.owner)return[];const n=["",t.fg("dim","FROM")];if(i.marketplace){const s=this.source?.marketplace?.revision;n.push(` ${t.fg("accent",i.marketplace)}${s?t.fg("dim",` @ ${s.slice(0,12)}`):""}`)}return i.source&&n.push(...m(" ",i.source,e)),(i.owner?.name||i.owner?.email)&&n.push(t.fg("dim",` owner \xB7 ${i.owner.name??i.owner.email}`)),n}sourceLines(i,e){const n=i?.marketplace,s=[];if(n===void 0?(s.push(t.fg("accent",t.bold(i?.label??"Library"))),s.push(t.fg("dim","Choose a marketplace or plugin to inspect it."))):(s.push(t.fg("accent",t.bold(n.name))),s.push(`Installed ${n.installedCount}/${n.pluginCount} plugins${t.fg("dim",` \xB7 ${w(n.updatableCount,"update","updates")}`)}`),s.push("",t.fg("dim","MARKETPLACE")),s.push(` ${t.fg("accent",n.scope)} scope \xB7 ${n.ref}`),s.push(...m(" ",n.url,e)),s.push(` ${t.fg("accent",n.path)}`),n.revision&&s.push(` revision \xB7 ${n.revision}${n.revisionDate?` \xB7 ${n.revisionDate}`:""}`),(n.owner?.name||n.owner?.email)&&s.push(` owner \xB7 ${n.owner.name??n.owner.email}`)),this.warnings.length>0){s.push("",t.fg("dim","PROBLEMS"));for(const r of this.warnings)s.push(...m(" ",r,e).map(a=>t.fg("warning",a)))}const o=this.marketplaceAction;if(o!==void 0&&o.sourceId===i?.id&&o.outcome.detail?.length){s.push("",t.fg("dim","LAST ACTION"));for(const r of o.outcome.detail)s.push(...m(" ",r,e))}return s}size(i){return i<1024?`${i} B`:i<1024*1024?`${Math.round(i/1024)} KB`:`${(i/(1024*1024)).toFixed(1)} MB`}}export{N as PkgDetailPanel};

package/dist/commands/pkg/browse/doc-view.d.ts

@@ -0,0 +1,3 @@
+import type { DocDetail } from './model.js';
+/** Every line of one memory doc's reader view, wrapped to `width`. */
+export declare function renderDocView(doc: DocDetail, width: number): string[];

package/dist/commands/pkg/browse/doc-view.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var h=(n,s)=>l(n,"name",{value:s,configurable:!0});import{getMarkdownTheme as g}from"@earendil-works/pi-coding-agent";import{Markdown as c,visibleWidth as p,wrapTextWithAnsi as $}from"@earendil-works/pi-tui";import{theme as r,wrapText as x}from"../../../core/tui/panel.js";function B(n,s){const t=[],i=Math.max(1,s);t.push(...o(n.name,i).map(e=>r.fg("accent",r.bold(e)))),t.push(r.fg("dim",n.kind)),n.shortForm&&(t.push(""),t.push(...a(n.shortForm,i))),t.push("",r.fg("dim","READ WHEN")),t.push(...a(n.routingLine||"Not declared.",i)),t.push("",r.fg("dim","ROUTING")),n.rules.length===0&&t.push(...a("No rules \u2014 reachable through directory listings and explicit reads only.",i));for(const e of n.rules){const u=[`deliver ${e.deliver}`];e.match?.length&&u.push(e.match.join(", ")),e.matchFrontmatter!==void 0&&u.push(JSON.stringify(e.matchFrontmatter)),e.if!==void 0&&u.push(`if ${JSON.stringify(e.if)}`),t.push(...f(e.on,u.join("  "),i))}return n.unlisted&&t.push(...f("unlisted","suppressed from directory listings",i)),n.rationale&&(t.push("",r.fg("dim","RATIONALE")),t.push(...a(n.rationale,i))),t.push("",r.fg("dim","ON DISK")),t.push(...f("path",n.path,i)),t.push(...f("size",N(n.sizeBytes),i)),t.push("",r.fg("dim","BODY"),""),t.push(...new c(n.body,0,0,g()).render(i)),t}h(B,"renderDocView");function a(n,s){return o(n,Math.max(1,s-2)).map(i=>`  ${r.fg("dim",i)}`)}h(a,"paragraph");function f(n,s,t){const i=`  ${n}  `,e=" ".repeat(p(i)),u=Math.max(1,t-p(i));return o(s,u).map((m,d)=>d===0?`${r.fg("accent",i)}${r.fg("dim",m)}`:`${e}${r.fg("dim",m)}`)}h(f,"field");function o(n,s){const t=n.trim();return t.split(/\s+/).some(i=>p(i)>s)?$(t,s):x(t,s)}h(o,"wrapped");function N(n){return n===void 0?"unknown":n<1024?`${n} B`:n<1024*1024?`${Math.round(n/1024)} KB`:`${(n/(1024*1024)).toFixed(1)} MB`}h(N,"size");export{B as renderDocView};

package/dist/commands/pkg/browse/list-panel.d.ts

@@ -0,0 +1,28 @@
+import type { CatalogSource, PluginEntry } from './model.js';
+/** The middle column of the plugin browser. It owns filtering and row position;
+ * the shell owns horizontal navigation and actions. */
+export declare class PkgListPanel {
+    private readonly onChange;
+    private source;
+    private index;
+    private filter;
+    private filtering;
+    private notice;
+    private hasMarketplaces;
+    constructor(onChange: () => void);
+    get selected(): PluginEntry | undefined;
+    get ownsKeyboard(): boolean;
+    setSource(source: CatalogSource, selectedKey?: string): void;
+    setEmptyState(hasMarketplaces: boolean): void;
+    move(delta: number): void;
+    /** Returns true only when a live filter consumed the input. */
+    handleInput(data: string): boolean;
+    setNotice(notice: string | undefined): void;
+    private entries;
+    render(width: number, height: number, focused: boolean): string[];
+    /** Pad rather than trim: this column sets the length of the divider drawn
+     *  beside it, and a divider that stops where the content runs out makes the
+     *  page look half-drawn. */
+    private fit;
+    private stateGlyph;
+}

package/dist/commands/pkg/browse/list-panel.js

@@ -0,0 +1,2 @@
+var I=Object.defineProperty;var C=(d,e)=>I(d,"name",{value:e,configurable:!0});import{matchesKey as c,truncateToWidth as n,visibleWidth as u}from"@earendil-works/pi-tui";import{padAnsi as N,theme as t,visibleRange as W}from"../../../core/tui/panel.js";import{displayVersion as G,plural as g}from"./model.js";class K{static{C(this,"PkgListPanel")}onChange;source;index=0;filter="";filtering=!1;notice;hasMarketplaces=!1;constructor(e){this.onChange=e}get selected(){const e=this.entries();return this.index=Math.max(0,Math.min(this.index,e.length-1)),e[this.index]}get ownsKeyboard(){return this.filtering}setSource(e,i){const r=this.source?.id!==e.id;this.source=e;const s=this.entries(),h=i===void 0?-1:s.findIndex(l=>l.key===i);this.index=h>=0?h:r?0:Math.min(this.index,Math.max(0,s.length-1)),r&&(this.filter="",this.filtering=!1)}setEmptyState(e){this.hasMarketplaces=e}move(e){const i=this.entries();i.length!==0&&(this.index=Math.max(0,Math.min(i.length-1,this.index+e)),this.onChange())}handleInput(e){return this.filtering?(c(e,"escape")?(this.filter="",this.filtering=!1):c(e,"enter")?this.filtering=!1:c(e,"backspace")?(this.filter=this.filter.slice(0,-1),this.index=0):e.length===1&&e.charCodeAt(0)>=32&&(this.filter+=e,this.index=0),this.onChange(),!0):e==="/"||c(e,"/")?(this.filtering=!0,this.onChange(),!0):c(e,"escape")&&this.filter!==""?(this.filter="",this.index=0,this.onChange(),!0):!1}setNotice(e){this.notice=e}entries(){const e=this.source?.entries??[],i=this.filter.trim().toLowerCase();return i===""?e:e.filter(r=>[r.name,r.description??"",...r.keywords].join(`
+`).toLowerCase().includes(i))}render(e,i,r){const s=[],h=this.source,l=this.entries(),y=h?.kind==="installed"?"Installed":h?.label??"Library",p=this.filtering?` /${this.filter} \xB7 ${g(l.length,"match","matches")}`:this.filter===""?` ${g(l.length,"plugin","plugins")}`:` ${g(l.length,"match","matches")} \xB7 esc clears`,v=Math.max(3,e-u(p));if(s.push(n(`${t.fg("accent",t.bold(n(y,v)))}${t.fg("dim",p)}`,e)),this.notice!==void 0&&s.push(n(t.fg("warning",`! ${this.notice}`),e)),l.length===0)return s.push(""),h?.kind==="installed"&&!this.hasMarketplaces?(s.push(n(t.fg("accent","No marketplaces yet."),e)),s.push(n(t.fg("dim","Press a to add a marketplace."),e))):(s.push(n(t.fg("dim","No plugins installed yet."),e)),s.push(n(t.fg("dim","Press tab to browse marketplaces."),e))),this.fit(s,i);const L=Math.max(1,i-s.length),m=W(l.length,this.index,L);for(let a=m.start;a<m.end;a+=1){const o=l[a],x=a===this.index,P=this.stateGlyph(o),b=G(o),$=`${P} ${o.name}`,k=b===void 0?"":` ${b}`,R=u($)+u(k),M=e-R-2,A=M>=12&&o.description?t.fg("dim",`  ${n(o.description,M)}`):"",f=n(`${$}${k}${A}`,e);s.push(x&&r?t.bg("selectedBg",N(f,e)):x?`${t.fg("accent","\u258C")}${n(t.fg("accent",f),Math.max(0,e-1))}`:f)}return this.fit(s,i)}fit(e,i){for(;e.length<i;)e.push("");return e.slice(0,i)}stateGlyph(e){return e.install.kind==="absent"?" ":e.install.scope==="builtin"?t.fg("muted","\u2302"):e.install.enabled?e.install.updateAvailable?t.fg("warning","\u2191"):t.fg("success","\u2713"):t.fg("dim","\u25CB")}}export{K as PkgListPanel};

package/dist/commands/pkg/browse/model.d.ts

@@ -0,0 +1,223 @@
+import type { Field, InputParam } from '../../../core/help.js';
+import type { RuleSpec } from '../../../core/graph/types.js';
+import type { OwnerRef, Scope } from '../../../types.js';
+/** The scopes that can hold a marketplace, and that a plugin can be installed
+ *  into. Narrower than `Scope`: `builtin` names plugins that ship with crtr, and
+ *  `listAllMarketplaces()` never yields it, so a builtin marketplace or a
+ *  builtin install target is not a state this surface can reach. */
+export type WritableScope = Exclude<Scope, "builtin">;
+/** Rail row identity: `installed`, or `market:<scope>:<name>`.
+ *
+ *  A marketplace id carries its scope because the same name can be registered
+ *  in both the user and the project scope. Collapsing those to one id makes two
+ *  distinct marketplaces share a row, and an action on it reach whichever one
+ *  the leaf's unscoped lookup resolves first — including a destructive one. */
+export type SourceId = string;
+export declare const INSTALLED_SOURCE_ID: SourceId;
+export declare function marketplaceSourceId(name: string, scope: WritableScope): SourceId;
+export type PluginInstallState = {
+    kind: "absent";
+} | {
+    kind: "installed";
+    scope: Scope;
+    enabled: boolean;
+    /** Version recorded for the installed copy, when it declares one. */
+    version?: string;
+    path: string;
+    /** The marketplace offers a version newer than the installed one. */
+    updateAvailable: boolean;
+};
+/** One command node a plugin contributes to the `crtr` tree, with the whole
+ *  contract an agent would read from `-h`. The browser renders the tree, so
+ *  children hang off their parent rather than arriving pre-flattened. */
+export interface CommandNode {
+    /** Path words from the crtr root, e.g. `['search', 'web']`. */
+    path: string[];
+    kind: "branch" | "leaf";
+    description: string;
+    /** The selection rubric — when to reach for this command. */
+    whenToUse: string;
+    summary: string;
+    tier?: "normal" | "common" | "important";
+    /** Empty for a leaf and for a passthrough branch. */
+    children: CommandNode[];
+    /** Branch only: forwards every argv token to an external binary instead of
+     *  parsing children. */
+    passthrough?: {
+        bin: string;
+        installHint: string;
+    };
+    /** Top-level branch only: its entry in the crtr root listing. */
+    rootEntry?: {
+        concept: string;
+        description: string;
+        whenToUse: string;
+    };
+    /** Leaf only: the exact invocation schema, straight from the manifest. */
+    params: InputParam[];
+    output: Field[];
+    effects: string[];
+    /** Leaf on an http-transport plugin only: the REST call it maps to. */
+    rest?: {
+        method: string;
+        path: string;
+        streaming: boolean;
+    };
+}
+/** `crtr exa-search web` — how a user types the command a node names. The one place
+ *  a command path becomes a label, so no corner of the page invents its own. */
+export declare function commandLabel(node: CommandNode): string;
+/** Every node in a command forest, parents before their children. */
+export declare function flattenCommands(nodes: CommandNode[]): CommandNode[];
+/** One memory doc a plugin provides — whole, because the resolver already read
+ *  the file to report the doc exists, so the body costs nothing extra.
+ *
+ *  Two fields sound alike and are not: `shortForm` is the human-facing hook —
+ *  what this doc SAYS — and is the description the page shows beside a doc's
+ *  name. `routingLine` is agent read-routing — WHEN to open it — and belongs
+ *  under the doc view's own heading, never in the description slot. */
+export interface DocDetail {
+    /** `<plugin>/<path>` — the identifier `crtr canvas read` takes. */
+    name: string;
+    kind: "knowledge" | "preference";
+    /** Frontmatter `short-form`: the abbreviated content. */
+    shortForm?: string;
+    /** Frontmatter `when-and-why-to-read`: one sentence routing a reading agent. */
+    routingLine?: string;
+    /** Absolute path to the `.md` on disk. */
+    path: string;
+    sizeBytes?: number;
+    /** Routing rules: when the doc delivers, and how much. Empty = reachable
+     *  through listings and explicit reads only. */
+    rules: RuleSpec[];
+    /** Suppressed from directory listings. */
+    unlisted: boolean;
+    /** The observed failure the doc exists to close. Maintainer-facing — never
+     *  delivered to a reading agent. */
+    rationale?: string;
+    /** Markdown body, frontmatter stripped. */
+    body: string;
+}
+/** A plugin as one list row: everything cheap enough to load for every row. */
+export interface PluginEntry {
+    /** Stable row key, unique across the whole catalog: `<sourceId>:<scope>:<name>`.
+     *  Scope participates because one name can name two different installations. */
+    key: string;
+    name: string;
+    /** What `pkg plugin install` takes: `<marketplace>/<plugin>`, else the name. */
+    ref: string;
+    sourceId: SourceId;
+    /** The marketplace offering it; absent for a plugin installed from a URL or path. */
+    marketplace?: string;
+    /** Version the marketplace offers (installed version lives in `install`). */
+    version?: string;
+    description?: string;
+    keywords: string[];
+    owner?: OwnerRef;
+    /** Upstream repo the marketplace entry points at. */
+    source?: string;
+    install: PluginInstallState;
+    /** Directory holding the plugin's files — the installed copy when there is
+     *  one, else the marketplace clone's vendored copy. Absent when neither
+     *  exists on disk, which is the only case where capability is unknowable. */
+    root?: string;
+}
+/** The version to show beside a plugin's name, anywhere in the page.
+ *
+ *  One rule, one place: the version beside a name is always the one in play on
+ *  THIS machine — what is installed, or what installing would get you. The
+ *  marketplace's offer for an already-installed plugin is a different fact, and
+ *  it appears only as the right-hand side of the update arrow in the status
+ *  line. Headline and list row both call this so they cannot disagree. */
+export declare function displayVersion(entry: PluginEntry): string | undefined;
+/** `<count> <noun>`, with the noun agreeing with the count. Every count this
+ *  page renders goes through here so no corner of it reads "1 docs". */
+export declare function plural(count: number, one: string, many: string): string;
+/** What a plugin adds to this machine — read from its directory on demand. */
+export interface PluginCapability {
+    /** Directory these facts were read from. */
+    root: string;
+    /** How crtr invokes its commands; null for a docs-only plugin. */
+    transport: "exec" | "http" | null;
+    /** Local executable (exec) or remote endpoint (http) — the trust-relevant fact. */
+    transportTarget?: string;
+    /** The command forest this plugin mounts, as a tree. */
+    commands: CommandNode[];
+    /** Static validation problems that stop a declared command from mounting. */
+    commandIssues: {
+        message: string;
+        next?: string;
+    }[];
+    docs: DocDetail[];
+    /** Total bytes on disk, when cheap to measure. */
+    sizeBytes?: number;
+}
+export interface MarketplaceDetail {
+    name: string;
+    scope: WritableScope;
+    url: string;
+    ref: string;
+    /** Absolute path to the clone. */
+    path: string;
+    owner?: OwnerRef;
+    version?: string;
+    pluginCount: number;
+    installedCount: number;
+    /** Installed plugins from this marketplace with a newer version offered. */
+    updatableCount: number;
+    /** Short sha of the clone's checked-out commit. */
+    revision?: string;
+    /** ISO date of that commit. */
+    revisionDate?: string;
+}
+export interface CatalogSource {
+    id: SourceId;
+    kind: "installed" | "marketplace";
+    label: string;
+    /** Present exactly when `kind === 'marketplace'`. */
+    marketplace?: MarketplaceDetail;
+    entries: PluginEntry[];
+}
+export interface Catalog {
+    sources: CatalogSource[];
+    /** Scopes a plugin can be installed into on this machine, in offer order. */
+    installScopes: WritableScope[];
+    /** Non-fatal problems loading the catalog — a broken clone, an unreadable
+     *  manifest. Surfaced in the page rather than thrown, so one bad marketplace
+     *  never takes the browser down. */
+    warnings: string[];
+}
+export type ActionKind = "install" | "remove" | "enable" | "disable" | "update" | "market-add" | "market-update" | "market-remove";
+export interface ActionRequest {
+    kind: ActionKind;
+    /** Required for every plugin-scoped action. */
+    entry?: PluginEntry;
+    /** Required for every marketplace-scoped action on an already-registered
+     *  marketplace (`market-update`, `market-remove`). */
+    marketplace?: string;
+    /** Git URL of the marketplace repo. Required by `market-add` only. */
+    url?: string;
+    /** Git ref the added marketplace tracks. `market-add` only; defaults to main. */
+    ref?: string;
+    /** The scope this action operates in — where `install` and `market-add` put
+     *  their result, and which of two same-named marketplaces `market-remove`
+     *  destroys. Ignored by actions that do not resolve a scope. */
+    scope?: WritableScope;
+}
+export interface ActionOutcome {
+    ok: boolean;
+    /** One line for the status row. */
+    message: string;
+    /** Extra lines for the detail pane — mounted commands, issues, git output. */
+    detail?: string[];
+}
+/** How an action presents before it runs: the progress line, and the question
+ *  to put in a confirm modal when the action destroys something. */
+export interface ActionPresentation {
+    /** Imperative label for the footer/menu, e.g. "Install into user scope". */
+    label: string;
+    /** Present-tense progress line, e.g. "Installing capture…". */
+    progress: string;
+    /** Non-empty only for destructive actions; the shell must confirm first. */
+    confirm?: string;
+}

package/dist/commands/pkg/browse/model.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var t=(n,r)=>o(n,"name",{value:r,configurable:!0});const l="installed";function p(n,r){return`market:${r}:${n}`}t(p,"marketplaceSourceId");function s(n){return`crtr ${n.path.join(" ")}`}t(s,"commandLabel");function i(n){return n.flatMap(r=>[r,...i(r.children)])}t(i,"flattenCommands");function u(n){return n.install.kind==="installed"?n.install.version??n.version:n.version}t(u,"displayVersion");function c(n,r,e){return`${n} ${n===1?r:e}`}t(c,"plural");export{l as INSTALLED_SOURCE_ID,s as commandLabel,u as displayVersion,i as flattenCommands,p as marketplaceSourceId,c as plural};

package/dist/commands/pkg/browse/shell.d.ts

@@ -0,0 +1,93 @@
+import { type Component, type Focusable, type TUI } from '@earendil-works/pi-tui';
+import { type BindingId, type BindingResolution } from '../../../core/keybindings/index.js';
+/** Full-screen plugin browser. The data and mutation boundaries stay in the
+ * catalog/actions collaborators, leaving this class responsible for movement,
+ * disclosure, and the rendered page grammar. */
+export declare class PkgBrowseShell implements Component, Focusable {
+    private readonly tui;
+    private readonly terminalRows;
+    private readonly bindings;
+    private catalog;
+    private sourceIndex;
+    private zone;
+    private readonly list;
+    private readonly detail;
+    private readonly capabilities;
+    private modal;
+    private busy;
+    private notice;
+    private _focused;
+    onCancel?: () => void;
+    constructor(tui: TUI, terminalRows: () => number, bindings: BindingResolution<BindingId>);
+    /** The page follows the user's own `crtr.setup.*` navigation gestures, the
+     *  same ones `crtr sys settings` resolves, alongside its literal defaults —
+     *  a remap must not leave one full-screen page moving and the other stuck. */
+    private matches;
+    /** The footer names keys, so it names the gestures actually bound. */
+    private label;
+    private isDown;
+    private isUp;
+    /** Move one zone to the right, or open the focused row. */
+    private isDescend;
+    /** Move one zone to the left. Escape is deliberately separate: in the dossier
+     *  it pops the whole view stack where `h` folds one branch. */
+    private isAscend;
+    /** Tab cycles rail sources from anywhere. The resolved `tab-next` gesture
+     *  also carries the horizontal arrows, which mean "into the panel" here, so
+     *  those are excluded exactly as the settings shell excludes them. */
+    private cyclesSource;
+    set focused(value: boolean);
+    get focused(): boolean;
+    /** Required by pi-tui's `Component`, and deliberately a no-op: this page
+     *  holds no render cache to drop. Every panel is recomputed each frame
+     *  because capability reads and action results land between input events. */
+    invalidate(): void;
+    dispose(): void;
+    private sources;
+    private get source();
+    private syncSource;
+    private syncDetail;
+    private reload;
+    private goSource;
+    private moveList;
+    private clearActionNotice;
+    /** A live filter, an open modal, or a running action holds every key — the
+     *  one predicate both `handleInput` and the footer consult, so the footer can
+     *  never advertise a key the filter is swallowing. */
+    private panelOwnsKeyboard;
+    handleInput(data: string): void;
+    private enterRail;
+    private enterList;
+    private enterDetail;
+    private jumpToInitial;
+    /** The focused rail row as an action subject. Carries the marketplace's scope
+     *  as well as its name: two marketplaces can share a name across the user and
+     *  project scopes, and without the scope `availableActions` cannot tell which
+     *  one a remove would destroy, so it offers nothing at all. */
+    private marketplaceSubject;
+    private triggerAction;
+    private openAdd;
+    private handleModal;
+    private submitAdd;
+    /** Where `a` registers a marketplace. Named once so the modal can state
+     *  exactly what the action will do. */
+    private addScope;
+    private execute;
+    private beginBusy;
+    private finishAction;
+    /** The source rail. It scrolls like the list does: marketplace count is user
+     *  controlled, so a fixed slice would let the selection sit below the last
+     *  drawn row, moving invisibly while the badge the user is aiming for never
+     *  appears. Group headings scroll with their group. */
+    private renderRail;
+    private renderPanel;
+    private renderModal;
+    private wrapModal;
+    private footer;
+    /** The footer names KEYS, not actions. An absent plugin offers a user-scope
+     *  and a project-scope install — two actions behind one `i`, which the scope
+     *  modal then chooses between — so the hints are deduped before joining. */
+    private availableActionHints;
+    render(width: number): string[];
+}
+export declare function runPkgBrowse(): Promise<void>;

package/dist/commands/pkg/browse/shell.js

@@ -0,0 +1 @@
+var D=Object.defineProperty;var k=(p,e)=>D(p,"name",{value:e,configurable:!0});import{Input as A,matchesKey as n,truncateToWidth as S,visibleWidth as m}from"@earendil-works/pi-tui";import{formatGesture as M,formatMovePair as L,matchesPiTuiInput as T}from"../../../core/keybindings/index.js";import{runTuiPage as C}from"../../../core/tui/page-host.js";import{PAGE_CHROME_ROWS as P,columns as b,framed as z,padAnsi as g,pageFrame as _,theme as o,visibleRange as N}from"../../../core/tui/panel.js";import{availableActions as $,presentAction as v,runAction as W}from"./actions.js";import{loadCapability as j,loadCatalog as w}from"./catalog.js";import{PkgDetailPanel as E}from"./detail-panel.js";import{PkgListPanel as H}from"./list-panel.js";import{INSTALLED_SOURCE_ID as O,marketplaceSourceId as U,plural as R}from"./model.js";const f=22,y=34,V=84,B=108;class K{static{k(this,"PkgBrowseShell")}tui;terminalRows;bindings;catalog;sourceIndex=0;zone="rail";list;detail=new E;capabilities=new Map;modal;busy;notice;_focused=!1;onCancel;constructor(e,t,i){this.tui=e,this.terminalRows=t,this.bindings=i,this.catalog=w(),this.list=new H(()=>this.tui.requestRender()),this.syncSource()}matches(e,t){return T(this.bindings,e,t,(i,s)=>n(i,s))}label(e,t){const i=this.bindings.gestures(e);return i.length===0?t:M(i[0].split(" > ").pop())}isDown(e){return n(e,"j")||n(e,"down")||this.matches("crtr.setup.list-down",e)}isUp(e){return n(e,"k")||n(e,"up")||this.matches("crtr.setup.list-up",e)}isDescend(e){return n(e,"l")||n(e,"right")||n(e,"enter")||this.matches("crtr.setup.advance",e)||this.matches("crtr.setup.open",e)}isAscend(e){return n(e,"h")||n(e,"left")}cyclesSource(e){const t=n(e,"right")||n(e,"left");return n(e,"tab")||!t&&this.matches("crtr.setup.tab-next",e)?1:n(e,"shift+tab")||!t&&this.matches("crtr.setup.tab-previous",e)?-1:0}set focused(e){this._focused=e}get focused(){return this._focused}invalidate(){}dispose(){this.busy!==void 0&&clearInterval(this.busy.timer)}sources(){return this.catalog.sources.length>0?this.catalog.sources:[{id:O,kind:"installed",label:"Installed",entries:[]}]}get source(){const e=this.sources();return this.sourceIndex=Math.max(0,Math.min(this.sourceIndex,e.length-1)),e[this.sourceIndex]}syncSource(e){this.list.setSource(this.source,e),this.syncDetail()}syncDetail(){const e=this.list.selected;let t=null;e!==void 0&&(this.capabilities.has(e.key)||(this.capabilities.set(e.key,void 0),Promise.resolve(j(e)).catch(()=>null).then(r=>{this.capabilities.set(e.key,r),this.list.selected?.key===e.key&&(this.syncDetail(),this.tui.requestRender())})),t=this.capabilities.get(e.key));const i=this.catalog.warnings,s=i[0];this.list.setNotice(s===void 0?void 0:i.length>1?`${s} \xB7 +${i.length-1} more`:s),this.list.setEmptyState(this.sources().some(r=>r.kind==="marketplace")),this.detail.setWarnings(i),this.detail.setEntry(e,this.source,t)}reload(e){const t=this.source.id;this.catalog=w(),this.capabilities.clear();const i=this.sources().findIndex(s=>s.id===t);this.sourceIndex=i>=0?i:0,this.syncSource(e)}goSource(e){const t=this.sources();this.sourceIndex=(this.sourceIndex+e+t.length)%t.length,this.clearActionNotice(),this.syncSource()}moveList(e){this.list.move(e),this.clearActionNotice(),this.syncDetail()}clearActionNotice(){this.notice=void 0}panelOwnsKeyboard(){return this.busy!==void 0||this.modal!==void 0||this.list.ownsKeyboard}handleInput(e){if(this.busy!==void 0)return;if(this.modal!==void 0){this.handleModal(e);return}if(this.list.ownsKeyboard&&this.list.handleInput(e)){this.clearActionNotice(),this.syncDetail();return}const t=this.cyclesSource(e);if(t!==0){this.goSource(t);return}if(n(e,"q")||this.matches("crtr.setup.cancel",e)){this.onCancel?.();return}if(this.zone==="rail"){this.isDown(e)?this.goSource(1):this.isUp(e)?this.goSource(-1):this.isDescend(e)?this.enterList():n(e,"escape")||n(e,"left")?this.onCancel?.():n(e,"a")?this.openAdd():this.triggerAction(e,void 0)||this.jumpToInitial(e);return}if(this.zone==="list"){if(this.list.handleInput(e)){this.clearActionNotice(),this.syncDetail();return}this.isDown(e)?this.moveList(1):this.isUp(e)?this.moveList(-1):this.isDescend(e)?this.enterDetail():this.isAscend(e)||n(e,"escape")?this.enterRail():this.triggerAction(e,this.list.selected);return}this.isDown(e)?this.detail.moveVertical(1):this.isUp(e)?this.detail.moveVertical(-1):n(e,"space")||this.matches("crtr.setup.toggle",e)?this.detail.toggleExpand():this.isDescend(e)?this.detail.open():this.isAscend(e)?this.detail.collapseOrPop()||this.enterList():n(e,"escape")?this.detail.escape()||this.enterList():this.triggerAction(e,this.list.selected)}enterRail(){this.zone="rail",this.clearActionNotice()}enterList(){this.zone="list",this.clearActionNotice(),this.syncDetail()}enterDetail(){this.list.selected===void 0&&this.source.marketplace===void 0||(this.zone="detail",this.clearActionNotice(),this.syncDetail())}jumpToInitial(e){if(e.length!==1||e.charCodeAt(0)<32)return;const t=e.toLowerCase(),i=this.sources().findIndex((s,r)=>r!==this.sourceIndex&&s.label.toLowerCase().startsWith(t));i>=0&&(this.sourceIndex=i,this.syncSource())}marketplaceSubject(){const e=this.source.marketplace;return e===void 0?{}:{marketplace:e.name,scope:e.scope}}triggerAction(e,t){const s=$(t===void 0?this.marketplaceSubject():{entry:t}).find(l=>l.kind==="install"&&n(e,"i")||(l.kind==="enable"||l.kind==="disable")&&n(e,"e")||(l.kind==="remove"||l.kind==="market-remove"?n(e,"x"):!1)||(l.kind==="update"||l.kind==="market-update"?n(e,"u"):!1));if(s===void 0)return!1;const r=v(s);return s.kind==="install"&&this.catalog.installScopes.length>1?this.modal={kind:"scope",request:s,presentation:r,index:0}:r.confirm?this.modal={kind:"confirm",request:s,presentation:r}:this.execute(s,r),!0}openAdd(){const e=new A,t=new A;e.focused=!0,this.modal={kind:"add",url:e,ref:t,field:"url"}}handleModal(e){const t=this.modal;t!==void 0&&(t.kind==="scope"?n(e,"escape")?this.modal=void 0:n(e,"j")||n(e,"down")?t.index=Math.min(this.catalog.installScopes.length-1,t.index+1):n(e,"k")||n(e,"up")?t.index=Math.max(0,t.index-1):n(e,"enter")&&(this.modal=void 0,this.execute({...t.request,scope:this.catalog.installScopes[t.index]},t.presentation)):t.kind==="confirm"?n(e,"y")||n(e,"enter")?(this.modal=void 0,this.execute(t.request,t.presentation)):(n(e,"n")||n(e,"escape"))&&(this.modal=void 0):n(e,"escape")?this.modal=void 0:n(e,"tab")?(t.field=t.field==="url"?"ref":"url",t.url.focused=t.field==="url",t.ref.focused=t.field==="ref"):n(e,"enter")?t.field==="url"?(t.field="ref",t.url.focused=!1,t.ref.focused=!0):this.submitAdd(t):(t.field==="url"?t.url:t.ref).handleInput(e))}submitAdd(e){const t=e.url.getValue().trim();if(t==="")return;const i=e.ref.getValue().trim();this.modal=void 0;const s={kind:"market-add",url:t,...i===""?{}:{ref:i},scope:this.addScope()};this.execute(s,v(s))}addScope(){return this.catalog.installScopes[0]??"user"}execute(e,t){const i=e.entry!==void 0?{kind:"plugin",key:e.entry.key}:e.marketplace===void 0||e.scope===void 0?void 0:{kind:"marketplace",sourceId:U(e.marketplace,e.scope)};this.beginBusy(t.progress),W(e).then(s=>this.finishAction(i,s))}beginBusy(e){const t={progress:e,frame:0,timer:setInterval(()=>{this.busy!==void 0&&(this.busy.frame=(this.busy.frame+1)%4,this.tui.requestRender())},125)};this.busy=t,this.tui.requestRender()}finishAction(e,t){if(this.busy!==void 0&&clearInterval(this.busy.timer),this.busy=void 0,this.notice={text:t.message,ok:t.ok},this.reload(e?.kind==="plugin"?e.key:void 0),this.syncDetail(),e?.kind==="plugin"){const i=this.sources().flatMap(s=>s.entries).find(s=>s.key===e.key);this.detail.setPluginAction(i,t)}else e?.kind==="marketplace"&&this.detail.setMarketplaceAction(e.sourceId,t);this.tui.requestRender()}renderRail(e,t){const i=[];let s=0,r=!1;for(const[c,a]of this.sources().entries()){a.kind==="installed"?i.push(o.fg("dim"," LIBRARY")):r||(i.length>0&&i.push(""),i.push(o.fg("dim"," MARKETPLACES")),r=!0);const d=a.kind==="installed"?String(a.entries.length):`${a.marketplace?.installedCount??0}/${a.marketplace?.pluginCount??a.entries.length}`,h=Math.max(1,e-m(d)-3),x=g(S(a.label,h),h),I=` ${x} ${d}`;c===this.sourceIndex&&(s=i.length),c===this.sourceIndex&&this.zone==="rail"?i.push(o.bg("selectedBg",g(I,e))):c===this.sourceIndex?i.push(`${o.fg("accent","\u258C")}${g(o.fg("accent",I.slice(1)),e-1)}`):i.push(g(` ${x} ${o.fg("dim",d)}`,e))}const l=N(i.length,s,t),u=i.slice(l.start,l.start+t);for(;u.length<t;)u.push("");return u}renderPanel(e,t,i){return this.modal!==void 0?this.renderModal(e,t):i==="detail"?this.detail.render(e,t,!0):this.list.render(e,t,i==="list")}renderModal(e,t){const i=this.modal;if(i===void 0)return[];let s;if(i.kind==="scope")s=[o.fg("accent",o.bold("Install into")),"",...this.catalog.installScopes.map((l,u)=>`${u===i.index?o.fg("accent","\u25B6"):" "} ${l}`)];else if(i.kind==="confirm")s=[o.fg("warning",o.bold(i.presentation.label)),"",...this.wrapModal(i.presentation.confirm??"Continue?",Math.max(1,e-4))];else{const l=Math.max(1,e-8);s=[o.fg("accent",o.bold("Add marketplace")),o.fg("dim",`Registers into ${this.addScope()} scope`),"","Git URL",i.field==="url"?i.url.render(l)[0]??"":i.url.getValue(),"","Ref (optional)",i.field==="ref"?i.ref.render(l)[0]??"":i.ref.getValue()]}const r=z(s,e);for(;r.length<t;)r.push("");return r.slice(0,t)}wrapModal(e,t){const i=e.trim().split(/\s+/),s=[];let r="";for(const l of i){const u=r===""?l:`${r} ${l}`;m(u)<=t?r=u:(r!==""&&s.push(r),r=l)}return r!==""&&s.push(r),s}footer(e){if(this.busy!==void 0){const d=["\u25D0","\u25D3","\u25D1","\u25D2"][this.busy.frame];return o.fg("warning",`${d} ${this.busy.progress}`)}if(this.modal?.kind==="scope")return o.fg("dim","\u2191\u2193/jk choose \xB7 enter install \xB7 esc cancel");if(this.modal?.kind==="confirm")return o.fg("dim","y/enter confirm \xB7 n/esc cancel");if(this.modal?.kind==="add")return o.fg("dim","tab field \xB7 enter next/add \xB7 esc cancel");if(this.list.ownsKeyboard)return o.fg("dim","type to filter \xB7 enter keep \xB7 esc clear");if(this.notice!==void 0)return o.fg(this.notice.ok?"success":"warning",this.notice.text);const t=this.availableActionHints(),i=this.zone,s=L(this.bindings,"crtr.setup.list-down","crtr.setup.list-up"),r=this.label("crtr.setup.advance","enter"),l=i==="rail"?`${s} source \xB7 a add`:i==="list"?`${s} row \xB7 / filter \xB7 ${r} dossier`:this.detail.viewing?`${s} scroll \xB7 esc back`:`${s} row \xB7 space expand \xB7 ${r} open \xB7 esc list`,u=i==="rail"?"type a letter to jump":"",c=`${this.label("crtr.setup.tab-next","tab")} source \xB7 ${this.label("crtr.setup.cancel","q")} close`,a=[[l,t,u],[l,t],[l]].map(d=>d.filter(h=>h!=="").join(" \xB7 "));for(const d of a){const h=e-m(d)-m(c);if(h>=2)return`${o.fg("dim",d)}${" ".repeat(h)}${o.fg("dim",c)}`}return o.fg("dim",S(`${l} \xB7 ${this.label("crtr.setup.cancel","q")} close`,e))}availableActionHints(){const e=this.zone==="rail"?void 0:this.list.selected,t=$(e===void 0?this.marketplaceSubject():{entry:e}).map(i=>{switch(i.kind){case"install":return"i install";case"enable":return"e enable";case"disable":return"e disable";case"remove":return"x remove";case"update":return"u update";case"market-add":return"a add";case"market-remove":return"x remove";case"market-update":return"u update"}});return[...new Set(t)].join(" \xB7 ")}render(e){const t=this.terminalRows(),i=Math.max(1,t-P),s=e>=V,r=e>=B;let l;if(r){const c=Math.max(1,e-f-y-6),a=b(this.list.render(y,i,this.zone==="list"),y,this.modal===void 0?this.detail.render(c,i,this.zone==="detail"):this.renderModal(c,i),c);l=b(this.renderRail(f,i),f,a,e-f-3)}else if(s){const c=e-f-3,a=this.zone==="detail"?"detail":"list";l=b(this.renderRail(f,i),f,this.renderPanel(c,i,a),c)}else this.modal!==void 0?l=this.renderModal(e,i):this.zone==="rail"?l=this.renderRail(e,i):l=this.renderPanel(e,i,this.zone==="detail"?"detail":"list");const u=s?`${R(this.sources().filter(c=>c.kind==="marketplace").length,"marketplace","marketplaces")} \xB7 ${R(this.sources().reduce((c,a)=>c+a.entries.length,0),"plugin","plugins")}`:`${this.source.label} \xB7 ${this.sourceIndex+1}/${this.sources().length}`;return _({width:e,height:t,title:"crouter plugins",meta:u,body:l,footer:this.footer(e)})}}async function ie(){if(!process.stdout.isTTY){process.stdout.write("crtr pkg browse needs a TTY. Run it in a terminal, or use `crtr pkg market browse` and `crtr pkg plugin list` for scriptable access.\n");return}await C(({tui:p,terminal:e,bindings:t},i)=>{const s=new K(p,()=>e.rows,t);return s.onCancel=i.cancel,s})}k(ie,"runPkgBrowse");export{K as PkgBrowseShell,ie as runPkgBrowse};

package/dist/commands/pkg/browse.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const pkgBrowseLeaf: LeafDef;

package/dist/commands/pkg/browse.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var e=(t,r)=>i(t,"name",{value:r,configurable:!0});import{defineLeaf as n}from"../../core/command.js";const p=n({name:"browse",description:"open the interactive plugin browser",whenToUse:"the user wants to browse registered marketplaces and inspect or manage plugins interactively. Agents should use pkg market browse or pkg plugin list, which are scriptable.",help:{name:"pkg browse",summary:"open the interactive plugin browser",inputNote:"No input parameters.",output:[],outputKind:"object",effects:["Opens a pi-tui page for browsing registered marketplaces, inspecting plugin capability surfaces, and managing plugins.","Requires a TTY. Without one it prints a pointer to pkg market browse and pkg plugin list and exits."]},run:e(async()=>{await(await import("./browse/shell.js")).runPkgBrowse()},"run"),render:e(()=>"","render")});export{p as pkgBrowseLeaf};

package/dist/commands/pkg/market-inspect.d.ts

@@ -0,0 +1,2 @@
+export declare const marketList: import("../../core/command.js").LeafDef;
+export declare const marketBrowse: import("../../core/command.js").LeafDef;

package/dist/commands/pkg/market-inspect.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var m=(r,o)=>y(r,"name",{value:o,configurable:!0});import{defineLeaf as k}from"../../core/command.js";import{notFound as x}from"../../core/errors.js";import{paginate as g}from"../../core/pagination.js";import{listInstalledPlugins as q,listInstalledMarketplaces as w,listAllMarketplaces as h,findMarketplaceByName as j}from"../../core/resolver.js";import{resolveScopeArg as b,projectScopeRoot as M}from"../../core/scope.js";const $=k({name:"list",description:"list registered marketplaces",whenToUse:"listing registered marketplace sources with their git URL, ref, scope, and clone path",help:{name:"pkg market list",summary:"list registered marketplaces",params:[{kind:"flag",name:"scope",type:"enum",choices:["user","project","all"],required:!1,constraint:"Default: all."},{kind:"flag",name:"limit",type:"int",required:!1,default:50,constraint:"Default 50, max 200."},{kind:"flag",name:"cursor",type:"string",required:!1,constraint:"Opaque token from next_cursor. Omit on first call."}],output:[{name:"items",type:"object[]",required:!0,constraint:"Each: {name, scope, url, ref, path}. Sorted by scope then name ascending."},{name:"next_cursor",type:"string | null",required:!0,constraint:"null means no more items."},{name:"total",type:"integer | null",required:!0,constraint:"Total count."}],outputKind:"object",effects:["None. Read-only."]},run:m(async r=>{const o=r.scope,l=r.limit,u=l!==void 0?Math.min(Math.max(1,l),200):50,c=r.cursor;let n;if(o!==void 0){const e=b(o);e==="all"?n=h():e==="builtin"?n=[]:n=w(e)}else n=h();const p=[...n].sort((e,i)=>e.scope==="project"&&i.scope!=="project"?-1:e.scope!=="project"&&i.scope==="project"?1:e.name.localeCompare(i.name)),s=g(p,{limit:u,cursor:c!==void 0?c:void 0},{defaultLimit:50,maxLimit:200,keyOf:m(e=>`${e.scope}:${e.name}`,"keyOf"),total:"count"});return{items:s.items.map(e=>({name:e.name,scope:e.scope,url:e.url,ref:e.ref,path:e.root})),next_cursor:s.next_cursor,total:s.total}},"run")}),N=k({name:"browse",description:"list plugins available in a marketplace",whenToUse:"browsing one registered marketplace source to choose a plugin install ref; each item includes ref=marketplace/plugin for `pkg plugin install`",help:{name:"pkg market browse",summary:"list plugins available in a marketplace",params:[{kind:"positional",name:"name",type:"string",required:!0,constraint:"Marketplace name."},{kind:"flag",name:"limit",type:"int",required:!1,default:50,constraint:"Default 50, max 200."},{kind:"flag",name:"cursor",type:"string",required:!1,constraint:"Opaque token from next_cursor. Omit on first call."}],output:[{name:"marketplace",type:"string",required:!0,constraint:"Echo of the input marketplace name."},{name:"items",type:"object[]",required:!0,constraint:"Each: {name, ref, source, version?, description?, keywords?, installed, installed_scope?}. ref is marketplace/plugin. Sorted by name ascending."},{name:"next_cursor",type:"string | null",required:!0,constraint:"null means no more items."},{name:"total",type:"integer | null",required:!0,constraint:"Total plugins in the marketplace; null if unavailable."}],outputKind:"object",effects:["None. Read-only."]},run:m(async r=>{const o=r.name,l=r.limit,u=l!==void 0?Math.min(Math.max(1,l),200):50,c=r.cursor,n=j(o);if(!n)throw x(`marketplace not found: ${o}`);const p=["project","user"].filter(t=>t!=="project"||M()!==null),s=new Map;for(const t of p)for(const a of q(t))s.has(a.name)||s.set(a.name,a.scope);const e=[...n.manifest.plugins].sort((t,a)=>t.name.localeCompare(a.name)),i=g(e,{limit:u,cursor:c!==void 0?c:void 0},{defaultLimit:50,maxLimit:200,keyOf:m(t=>t.name,"keyOf"),total:"count"});return{marketplace:n.name,items:i.items.map(t=>{const a=s.get(t.name),d=a!==void 0,f={name:t.name,ref:`${n.name}/${t.name}`,source:t.source,version:t.version,description:t.description,keywords:t.keywords,installed:d};return d&&(f.installed_scope=a),f}),next_cursor:i.next_cursor,total:i.total}},"run")});export{N as marketBrowse,$ as marketList};

package/dist/commands/pkg/market-manage.d.ts

@@ -0,0 +1,16 @@
+import type { Scope } from '../../types.js';
+/** Clone a marketplace repo into `scope` and register it in that scope's
+ *  config. Shared by the `pkg market add` leaf and `crtr sys setup`, which
+ *  offers the official marketplace as a checked-by-default entry. */
+export declare function addMarketplace(opts: {
+    url: string;
+    ref?: string;
+    scope: Scope;
+}): {
+    name: string;
+    scope: Scope;
+    path: string;
+};
+export declare const marketAdd: import("../../core/command.js").LeafDef;
+export declare const marketRemove: import("../../core/command.js").LeafDef;
+export declare const marketUpdate: import("../../core/command.js").LeafDef;

package/dist/commands/pkg/market-manage.js

@@ -0,0 +1 @@
+var J=Object.defineProperty;var m=(o,n)=>J(o,"name",{value:n,configurable:!0});import{dirname as R,join as g,relative as Q,resolve as M}from"node:path";import{renameSync as y}from"node:fs";import{defineLeaf as D}from"../../core/command.js";import{general as j,notFound as d}from"../../core/errors.js";import{listAllMarketplaces as I,listAllPlugins as W,findMarketplaceByName as w}from"../../core/resolver.js";import{resolveScopeArg as C,requireScopeRoot as S,marketplacesDir as X,pluginsDir as Y}from"../../core/scope.js";import{updateConfig as q,updateState as G,ensureScopeInitialized as Z,readConfig as ee}from"../../core/config.js";import{pathExists as $,ensureDir as L,removePath as f,isSymlink as te,nowIso as N,readSymlinkTarget as oe}from"../../core/fs-utils.js";import{clone as _,deriveNameFromUrl as ne,currentSha as K,gitSync as O,isGitRepo as E}from"../../core/git.js";import{readMarketplaceManifest as U,readPluginManifest as F}from"../../core/manifest.js";import{assertPluginCandidateValid as re,isMarketplaceRelativeSource as ae}from"./plugin-manage.js";import{resolveInstallScope as se}from"./shared.js";function ie(o){const{url:n,ref:s,scope:t}=o,i=S(t);Z(t,i);const p=ne(n),c=X(t);L(c);const l=g(c,p);$(l)&&f(l),_(n,l,{depth:1,ref:s!==void 0?s:void 0});const u=U(l);if(!u)throw f(l),d(`marketplace manifest not found at ${l}/.crouter-marketplace/marketplace.json \u2014 not a valid marketplace`);const e=u.name,r=g(c,e);e!==p&&($(r)&&f(r),y(l,r));const a=s!==void 0?s:"main";return q(t,k=>{k.marketplaces[e]={url:n,ref:a,installed_at:N()}}),{name:e,scope:t,path:r}}m(ie,"addMarketplace");const Re=D({name:"add",description:"add a marketplace by git URL",whenToUse:"registering a new marketplace source repo so its plugins appear in marketplace browse output and become installable by marketplace/plugin ref",help:{name:"pkg market add",summary:"add a marketplace by git URL",params:[{kind:"positional",name:"url",type:"string",required:!0,constraint:"Git URL of the marketplace repo."},{kind:"flag",name:"ref",type:"string",required:!1,constraint:"Git ref to track. Default: main."},{kind:"flag",name:"scope",type:"enum",choices:["user","project"],required:!1,constraint:"Default: project if available, else user."}],output:[{name:"name",type:"string",required:!0,constraint:"Marketplace name as declared in marketplace.json."},{name:"scope",type:"string",required:!0,constraint:"Scope the marketplace was added into."},{name:"path",type:"string",required:!0,constraint:"Absolute path to the cloned marketplace directory."}],outputKind:"object",effects:["Clones the marketplace repo. Registers the marketplace in config.json."]},run:m(async o=>{const n=o.url,s=o.ref,t=o.scope;return ie({url:n,ref:s,scope:se(t)})},"run")}),je=D({name:"remove",description:"remove a marketplace",whenToUse:"unregistering a marketplace source: deletes the source clone and any plugins installed from it in the same scope",help:{name:"pkg market remove",summary:"remove a marketplace and its directory",params:[{kind:"positional",name:"name",type:"string",required:!0,constraint:"Marketplace name to remove."},{kind:"flag",name:"scope",type:"enum",choices:["user","project"],required:!1,constraint:"Narrows resolution."}],output:[],outputKind:"object",effects:["Deletes the marketplace directory. Removes the entry from config.json. Removes plugin files and config entries sourced from that marketplace in the same scope."]},run:m(async o=>{const n=o.name,s=o.scope;let t,i;if(s!==void 0){const r=C(s);if(r!=="all"&&r!=="builtin"){const a=r,k=w(n,a);if(!k)throw d(`marketplace not found: ${n} (scope: ${a})`);t=a,i=k.root}else{const a=w(n);if(!a)throw d(`marketplace not found: ${n}`);t=a.scope,i=a.root}}else{const r=w(n);if(!r)throw d(`marketplace not found: ${n}`);t=r.scope,i=r.root}const p=t,c=S(p),l=Y(p),u=ee(p),e=[];for(const[r,a]of Object.entries(u.plugins))a.source_marketplace===n&&e.push(r);for(const r of e){const a=g(l,r);f(a)}return f(i),q(p,r=>{delete r.marketplaces[n];for(const a of e)delete r.plugins[a]}),{}},"run")});function z(o,n,s,t){try{_(o,t,{depth:1,ref:n})}catch(i){throw f(t),i}return{active:s,candidate:t,previous:`${t}.previous`}}m(z,"stageGitRoot");function ce(o){const n=[],s=[];try{for(const t of o){if($(t.previous))throw j(`prior staged backup remains at ${t.previous}`);y(t.active,t.previous),n.push(t)}for(const t of o)y(t.candidate,t.active),s.push(t)}catch(t){for(const i of[...s].reverse())y(i.active,i.candidate);for(const i of[...n].reverse())y(i.previous,i.active);throw t}for(const t of o)f(t.previous)}m(ce,"activateStagedRoots");function B(o,n,s){return{plugin:{...o,root:n,manifest:s},scopeRoot:R(R(o.root))}}m(B,"candidatePlugin");async function pe(o){const n=K(o.root)??"",s=W().filter(u=>u.scope===o.scope&&u.sourceMarketplace===o.name),t=[],i=[];let p,c;const l=[];try{if(E(o.root)){const e=g(R(o.root),`.${o.name}.${process.pid}.${Date.now()}.candidate`);c=z(o.url,o.ref,o.root,e),i.push(e);const r=U(e);if(r===null)throw d(`marketplace manifest not found in candidate checkout: ${e}/.crouter-marketplace/marketplace.json`);p=r,t.push(c)}else{const e=U(o.root);if(e===null)throw d(`marketplace manifest not found after refresh: ${o.root}/.crouter-marketplace/marketplace.json`);p=e}for(const e of s){if(te(e.root)){if(c===void 0)continue;const b=p.plugins.find(V=>V.name===e.name);if(b===void 0||!ae(b.source))throw j(`marketplace candidate removes relative-source plugin "${e.name}" while it is installed`);const T=oe(e.root);if(T===null)throw j(`installed marketplace plugin "${e.name}" has no readable symlink target`);const x=Q(o.root,M(R(e.root),T)),h=M(c.candidate,b.source);if(h!==M(c.candidate,x))throw j(`marketplace candidate moves installed relative-source plugin "${e.name}" from ${x} to ${b.source}`);if(!$(h))throw d(`marketplace candidate source path does not exist for plugin "${e.name}": ${h}`);const A=F(h);if(A===null)throw d(`plugin manifest not found in marketplace candidate: ${h}/.crouter-plugin/plugin.json`);l.push(B(e,h,A));continue}if(!$(e.root)||!E(e.root))continue;const r=O(["config","--get","remote.origin.url"],e.root).stdout.trim(),a=O(["symbolic-ref","--short","HEAD"],e.root).stdout.trim();if(r===""||a==="")continue;const k=e.scope==="project"?S("project"):S("user"),v=g(k,"tmp",`${e.name}.${process.pid}.${Date.now()}.candidate`);L(g(k,"tmp"));const H=z(r,a,e.root,v);i.push(v);const P=F(v);if(P===null)throw d(`plugin manifest not found in update candidate: ${v}/.crouter-plugin/plugin.json`);l.push(B(e,v,P)),t.push(H)}for(const e of l)await re(e.plugin.manifest,e.plugin.root,e.plugin.scope,e.scopeRoot,`${e.plugin.root}/.crouter-plugin/plugin.json`,l);ce(t),G(o.scope,e=>{e.marketplaces[o.name]===void 0&&(e.marketplaces[o.name]={}),e.marketplaces[o.name].last_updated=N()});for(const e of s){const r=p.plugins.find(a=>a.name===e.name);r?.version!==void 0&&q(e.scope,a=>{a.plugins[e.name]!==void 0&&(a.plugins[e.name].version=r.version)}),G(e.scope,a=>{a.plugins[e.name]===void 0&&(a.plugins[e.name]={}),a.plugins[e.name].last_updated=N()})}const u=K(o.root)??"";return{name:o.name,updated:n!==u,sha:u}}finally{for(const u of i)f(u)}}m(pe,"updateMarketplaceTarget");const Se=D({name:"update",description:"replace marketplace source with its latest revision",whenToUse:"refreshing one named marketplace source from git, or all registered marketplace sources when no name is given; also updates installed plugins sourced from refreshed marketplaces",help:{name:"pkg market update",summary:"refresh one or all registered marketplaces",params:[{kind:"flag",name:"name",type:"string",required:!1,constraint:"Marketplace name to update. Omit to update all registered marketplaces."},{kind:"flag",name:"scope",type:"enum",choices:["user","project"],required:!1,constraint:"Narrows resolution."}],output:[{name:"updated",type:"object[]",required:!0,constraint:"One entry per marketplace processed: {name, updated, sha}."}],outputKind:"object",effects:["Stages and validates marketplace and sourced-plugin revisions before atomically activating them, replacing each checkout even at an unchanged revision \u2014 local modifications inside those directories are discarded. `updated` reports whether the revision moved, not whether the checkout was replaced. Updates installed plugin content/version for plugins sourced from refreshed marketplaces."]},run:m(async o=>{const n=o.name,s=o.scope,t=s===void 0?void 0:C(s),i=n===void 0?t===void 0||t==="all"?I():t==="builtin"?[]:I().filter(c=>c.scope===t):(()=>{const c=t===void 0||t==="all"||t==="builtin"?w(n):w(n,t);if(c===null)throw d(`marketplace not found: ${n}${t===void 0||t==="all"||t==="builtin"?"":` (scope: ${t})`}`);return[c]})(),p=[];for(const c of i)p.push(await pe(c));return{updated:p}},"run")});export{ie as addMarketplace,Re as marketAdd,je as marketRemove,Se as marketUpdate};