@hanamesh/dsh-app-host 0.2.0-rc.2

package/dist/library/install.js

@@ -0,0 +1,87 @@
+import { readFile, lstat, unlink, rmdir } from 'node:fs/promises';
+import { join, resolve, dirname, sep } from 'node:path';
+import { spawn as nodeSpawn } from 'node:child_process';
+import { AppHostError, requireCondition } from '../errors.js';
+import { validateDefinition } from '../descriptor.js';
+import { itemKind } from './catalog.js';
+
+/** The HanaMesh suite itself (real names + the historical scoped spellings) is never installed or removed through the market. */
+export const PROTECTED_PACKAGES=Object.freeze(['@hanamesh/dsh-app-host','hanamesh-core','hanamesh-usage','@hanamesh/dsh-core','@hanamesh/dsh-usage']);
+const blocked=new Set(PROTECTED_PACKAGES);
+const packageName=value=>typeof value==='string'&&/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
+const versionText=value=>typeof value==='string'&&/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
+async function json(path){return JSON.parse(await readFile(path,'utf8'));}
+function defaultSpawn(command,args,options){return new Promise((resolvePromise,reject)=>{const child=nodeSpawn(command,args,{...options,env:{HOME:process.env.HOME,DSH_HOME:process.env.DSH_HOME,LANG:process.env.LANG??'C.UTF-8',PATH:`${command.slice(0,command.lastIndexOf('/'))}:/usr/bin:/bin`},stdio:['ignore','pipe','pipe']});let stdout='',stderr='';child.stdout.on('data',chunk=>stdout+=chunk);child.stderr.on('data',chunk=>stderr+=chunk);child.on('error',reject);child.on('exit',(code,signal)=>resolvePromise({code,signal,stdout,stderr}));});}
+
+async function defaults(){return await import('../provision/index.js');}
+
+/** Runtime-created Python import caches are disposable. Preserve every other unowned file. */
+async function clearGeneratedRuntimeCache(result,runtimeRoot){
+  if(!Array.isArray(result?.kept)||result.kept.length===0)return;
+  const target=resolve(result.target??'');
+  requireCondition(target.startsWith(resolve(runtimeRoot)+sep),'RUNTIME_RESIDUE','Runtime cleanup target is outside the application runtime root.');
+  const remaining=[];
+  for(const rel of result.kept){
+    if(typeof rel!=='string'||!/(?:^|\/)__pycache__\/[^/]+\.pyc$/.test(rel)){remaining.push(rel);continue;}
+    const file=resolve(target,rel);
+    if(!file.startsWith(target+sep)){remaining.push(rel);continue;}
+    const info=await lstat(file).catch(error=>error.code==='ENOENT'?null:Promise.reject(error));
+    if(!info?.isFile()){remaining.push(rel);continue;}
+    await unlink(file);
+    for(let dir=dirname(file);dir.startsWith(target+sep);dir=dirname(dir)){
+      try{await rmdir(dir);}catch(error){if(error.code==='ENOTEMPTY'||error.code==='ENOENT')break;throw error;}
+    }
+  }
+  if(remaining.length===0){try{await rmdir(target);}catch(error){if(error.code!=='ENOTEMPTY'&&error.code!=='ENOENT')throw error;}}
+  const residue=await lstat(target).catch(error=>error.code==='ENOENT'?null:Promise.reject(error));
+  requireCondition(remaining.length===0&&residue===null,'RUNTIME_RESIDUE','Runtime has unowned files that require manual review.',{count:remaining.length},409);
+}
+
+export function createLibraryInstaller({profileDir,profileName,dataRoot,nodeBinary,dshBin,registry='https://registry.npmjs.org',allowPrerelease=false,
+  fetchImpl=globalThis.fetch,spawn=defaultSpawn,provision,remove,emit=()=>{}}){
+  requireCondition(typeof profileDir==='string'&&resolve(profileDir)===profileDir,'PROFILE_DIR_REQUIRED','library.profileDir must be an absolute path.');
+  requireCondition(typeof dataRoot==='string'&&resolve(dataRoot)===dataRoot,'INVALID_ROOT','dataRoot must be absolute.');
+  requireCondition(typeof nodeBinary==='string'&&resolve(nodeBinary)===nodeBinary,'NODE_RUNTIME_REQUIRED','An absolute nodeBinary is required for library operations.');
+  requireCondition(typeof dshBin==='string'&&resolve(dshBin)===dshBin,'DSH_BIN_REQUIRED','An absolute DSH bin.js path is required.');
+  requireCondition(typeof profileName==='string'&&/^[A-Za-z0-9_.-]+$/.test(profileName),'PROFILE_NAME_REQUIRED','library.profileName is required.');
+  const runtimeRoot=appId=>join(dataRoot,'runtimes',appId);
+  const permitted=name=>requireCondition(packageName(name)&&!blocked.has(name),'PACKAGE_DENIED','Package name is not permitted.',{packageName:name});
+  async function installed(packageNameValue){const root=join(profileDir,'node_modules',...packageNameValue.split('/')),pkg=await json(join(root,'package.json'));const appFile=typeof pkg.hanamesh?.app==='string'?pkg.hanamesh.app:'app.json';return{pkg,definition:validateDefinition(await json(join(root,appFile)))};}
+  async function run(args){const result=await spawn(nodeBinary,[dshBin,'plugin','--profile',profileName,...args],{cwd:profileDir});requireCondition(result.code===0,'DSH_PLUGIN_FAILED','DSH plugin operation failed.',{code:result.code,signal:result.signal,stderr:String(result.stderr??'').slice(-2000)},502);return result;}
+  /** The exact version `dsh plugin add` will pin: the registry's `latest` dist-tag, re-checked here (the catalog's `latestVersion` is a hint only). */
+  async function latest(name){
+    const base=new URL(registry);requireCondition(['https:','http:'].includes(base.protocol),'REGISTRY_DENIED','Registry URL is invalid.');
+    const target=new URL(`${base.href.replace(/\/$/,'')}/${encodeURIComponent(name)}/latest`);const response=await fetchImpl(target,{headers:{accept:'application/json','accept-encoding':'identity'}});
+    requireCondition(response.ok,'REGISTRY_LOOKUP_FAILED','Registry latest lookup failed.',{status:response.status},502);const metadata=await response.json();const version=metadata.version;
+    requireCondition(versionText(version)&&(allowPrerelease||!version.includes('-')),'UNSTABLE_VERSION','Registry latest must be an exact stable version.');
+    return version;
+  }
+  /** Same path for applications and plugins: `dsh plugin add --save-exact <name>@<version>` (also the upgrade path: a newer exact version replaces the installed one). */
+  async function add(name){const version=await latest(name);await run(['add','--save-exact',`${name}@${version}`]);return version;}
+  return{
+    async install(item){
+      const kind=itemKind(item);
+      requireCondition(kind!=='listing','NOT_INSTALLABLE','Catalog item has no npm package to install.');const name=item.package.name;
+      permitted(name);
+      emit({type:'library.install-started',itemId:item.id,packageName:name,kind});
+      try{
+        const version=await add(name);
+        if(kind==='plugin'){const result={status:'restart-required',kind,packageName:name,version};emit({type:'library.install-done',...result});return result;}
+        const record=await installed(name);const runtime=record.definition.deployments.map(deployment=>deployment.runtime).find(Boolean);
+        if(runtime){const api=provision?{provision}:{...(await defaults())};await api.provision(runtime.manifest,{root:runtimeRoot(record.definition.id),only:[runtime.item],onProgress:event=>emit({type:'library.provision-progress',appId:record.definition.id,...event})});}
+        const result={status:'restart-required',kind,appId:record.definition.id,packageName:name,version};emit({type:'library.install-done',...result});return result;
+      }catch(error){emit({type:'library.install-failed',itemId:item.id,packageName:name,kind,code:error.code??'INSTALL_FAILED'});throw error;}
+    },
+    /** rc.28: install a plugin by package name (already verified against the catalog by the service). */
+    async installPlugin({packageName:name}){
+      permitted(name);
+      emit({type:'library.install-started',packageName:name,kind:'plugin'});
+      try{const version=await add(name);const result={status:'restart-required',kind:'plugin',packageName:name,version};emit({type:'library.install-done',...result});return result;}
+      catch(error){emit({type:'library.install-failed',packageName:name,kind:'plugin',code:error.code??'INSTALL_FAILED'});throw error;}
+    },
+    async provisionRuntime({appId,packageName:installedName,runtimeItem}){const record=await installed(installedName);requireCondition(record.definition.id===appId,'APP_ID_MISMATCH','Installed package app id does not match.');const runtime=record.definition.deployments.map(deployment=>deployment.runtime).find(value=>value?.item===runtimeItem);requireCondition(runtime,'RUNTIME_NOT_DECLARED','Runtime item is not declared.');const api=provision?{provision}:{...(await defaults())};const result=await api.provision(runtime.manifest,{root:runtimeRoot(appId),only:[runtime.item],onProgress:event=>emit({type:'library.provision-progress',appId,...event})});return{status:'restart-required',appId,packageName:installedName,result};},
+    async uninstall({packageName:installedName,appId,runtimeItem,running}){permitted(installedName);requireCondition(!running,'INSTANCE_IN_USE','Stop all application instances before uninstalling.',{},409);await run(['remove',installedName]);if(runtimeItem){const api=remove?{remove}:{...(await defaults())};const result=await api.remove(runtimeItem,{root:runtimeRoot(appId)});await clearGeneratedRuntimeCache(result,runtimeRoot(appId));}return{status:'restart-required',kind:'application',appId,packageName:installedName,dataPreserved:true};},
+    /** rc.28: `dsh plugin remove <name>`; the suite itself (PROTECTED_PACKAGES) is refused with PACKAGE_DENIED. */
+    async uninstallPlugin({packageName:installedName}){permitted(installedName);await run(['remove',installedName]);return{status:'restart-required',kind:'plugin',packageName:installedName};},
+  };
+}

package/dist/library/installed.js

@@ -0,0 +1,67 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { requireCondition } from '../errors.js';
+import { validateDefinition } from '../descriptor.js';
+
+async function json(path){return JSON.parse(await readFile(path,'utf8'));}
+const absolute=profileDir=>requireCondition(typeof profileDir==='string'&&resolve(profileDir)===profileDir,'PROFILE_DIR_REQUIRED','library.profileDir must be an absolute path.');
+
+/** The profile manifest written by `dsh plugin`: `dependencies` = every package the user added; `dsh.profile.bundles` = the active layer stack. */
+export async function readProfileManifest(profileDir){
+  absolute(profileDir);
+  let profile;try{profile=await json(join(profileDir,'package.json'));}catch{profile={};}
+  return{dependencies:{...(profile.dependencies??{})},bundles:[...(profile.dsh?.profile?.bundles??[])]};
+}
+async function packageRoots(profileDir){
+  const names=new Set(Object.keys((await readProfileManifest(profileDir)).dependencies));
+  const scope=join(profileDir,'node_modules','@hanamesh');
+  for(const name of await readdir(scope).catch(()=>[]))if(name.startsWith('app-'))names.add(`@hanamesh/${name}`);
+  return[...names].map(name=>({name,root:join(profileDir,'node_modules',...name.split('/'))}));
+}
+
+export async function scanInstalled({profileDir,host,ledgerReader,dataRoot}){
+  absolute(profileDir);
+  const registered=new Set((host.list().apps??[]).map(app=>app.id));const rows=[];
+  for(const candidate of await packageRoots(profileDir)){
+    let pkg;try{pkg=await json(join(candidate.root,'package.json'));}catch{continue;}
+    const declaration=pkg.hanamesh?.app;if(!declaration)continue;
+    const appFile=typeof declaration==='string'?declaration:'app.json';
+    let definition;try{definition=validateDefinition(await json(join(candidate.root,appFile)));}catch(error){rows.push({packageName:pkg.name??candidate.name,version:pkg.version,state:'invalid',errorCode:error.code??'INVALID_DEFINITION'});continue;}
+    const runtime=definition.deployments.map(deployment=>deployment.runtime).find(Boolean);let state=registered.has(definition.id)?'registered':'installed-not-loaded';
+    if(runtime){const book=await ledgerReader(join(dataRoot,'runtimes',definition.id));if(!book.items?.[runtime.item])state='runtime-missing';}
+    rows.push({packageName:pkg.name??candidate.name,version:pkg.version,appId:definition.id,name:definition.name,state,definition,runtimeItem:runtime?.item});
+  }
+  return rows.sort((a,b)=>(a.packageName??'').localeCompare(b.packageName??''));
+}
+
+/**
+ * rc.28 market: every `dependencies` entry of the profile that is NOT a HanaMesh application package is a plugin
+ * (or a plain library) installed by `dsh plugin add`. The pinned kernel exposes nothing about what the running
+ * process loaded, so "needs a restart" is derived from the dependency set observed when this plugin started
+ * (`bootDependencies`): added since boot → `installed-not-loaded`; gone since boot → `uninstalled-not-unloaded`
+ * (still running until DSH restarts); otherwise `installed`. No snapshot (undefined) → everything present counts as loaded. `bundle` = the package declares `dsh.bundle`
+ * (a profile layer), `active` = it is in `dsh.profile.bundles`.
+ */
+export async function scanInstalledPlugins({profileDir,bootDependencies}){
+  const loaded=name=>bootDependencies===undefined||name in bootDependencies;
+  const manifest=await readProfileManifest(profileDir);const rows=[];
+  for(const name of Object.keys(manifest.dependencies)){
+    let pkg;try{pkg=await json(join(profileDir,'node_modules',...name.split('/'),'package.json'));}catch{pkg=undefined;}
+    if(pkg?.hanamesh?.app)continue;
+    rows.push({packageName:name,version:pkg?.version??null,kind:'plugin',bundle:Boolean(pkg?.dsh?.bundle?.patch),active:manifest.bundles.includes(name),
+      state:pkg===undefined?'invalid':loaded(name)?'installed':'installed-not-loaded',...(pkg===undefined?{errorCode:'PACKAGE_UNREADABLE'}:{})});
+  }
+  for(const name of Object.keys(bootDependencies??{}))if(!(name in manifest.dependencies)&&!bootDependencies[name]?.application)
+    rows.push({packageName:name,version:bootDependencies[name]?.version??null,kind:'plugin',bundle:Boolean(bootDependencies[name]?.bundle),active:false,state:'uninstalled-not-unloaded'});
+  return rows.sort((a,b)=>a.packageName.localeCompare(b.packageName));
+}
+
+/** Snapshot taken at plugin start: which dependencies existed, and which of them are application packages. */
+export async function snapshotProfileDependencies(profileDir){
+  const manifest=await readProfileManifest(profileDir);const snapshot={};
+  for(const name of Object.keys(manifest.dependencies)){
+    let pkg;try{pkg=await json(join(profileDir,'node_modules',...name.split('/'),'package.json'));}catch{pkg=undefined;}
+    snapshot[name]={version:pkg?.version??null,application:Boolean(pkg?.hanamesh?.app),bundle:Boolean(pkg?.dsh?.bundle?.patch)};
+  }
+  return snapshot;
+}

package/dist/library/locate.js

@@ -0,0 +1,79 @@
+/**
+ * Library locations on plain DSH (PRD §A.8 official-distribution path, rc.26).
+ *
+ * The pinned kernel exposes neither the profile directory nor the profile name to a plugin, and the
+ * desktop shell fills `library.profileDir/profileName/dshBin` and `nodeBinary` through its overlay.
+ * A `dsh plugin add` user has no overlay, so without these the installed-app scan returned `[]` and
+ * every install/uninstall answered `LIBRARY_INSTALL_UNAVAILABLE`. Each value below is inferred ONLY
+ * when the explicit config leaves it undefined, and only from facts this process can prove about
+ * itself: where its own package really lives, which script started it, and which Node runs it.
+ */
+import { readFile, realpath } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PACKAGE_NAME='@hanamesh/dsh-app-host';
+/** Used when `library.sources` is undefined (not configured). An explicit `[]` means "no source". */
+export const DEFAULT_CATALOG_SOURCES=Object.freeze([Object.freeze({manifestUrl:'https://market.hanamesh.com/catalog-source.json',enabled:true})]);
+const DSH_BIN_SUFFIX='/@deepseek-ai/dsh/lib/bin.js';
+
+async function json(path){try{return JSON.parse(await readFile(path,'utf8'));}catch{return undefined;}}
+/** A DSH profile manifest that carries HanaMesh: `dsh.profile` (written by `dsh plugin`) or a hanamesh dependency. */
+export function isHanameshProfileManifest(manifest){
+  if(!manifest||typeof manifest!=='object'||Array.isArray(manifest))return false;
+  const hanamesh=name=>typeof name==='string'&&/hanamesh/.test(name);
+  const bundles=manifest.dsh?.profile?.bundles;
+  return(Array.isArray(bundles)&&bundles.some(hanamesh))||Object.keys(manifest.dependencies??{}).some(hanamesh);
+}
+
+/** Real directory of the package that owns `moduleUrl`: walk up to the package.json named PACKAGE_NAME. */
+export async function packageRoot(moduleUrl){
+  let dir=dirname(fileURLToPath(moduleUrl));
+  for(;;){
+    if((await json(join(dir,'package.json')))?.name===PACKAGE_NAME)return await realpath(dir);
+    const parent=dirname(dir);if(parent===dir)return undefined;dir=parent;
+  }
+}
+
+/**
+ * The profile that lists this package: the nearest ancestor of the REAL package root whose
+ * `node_modules/@hanamesh/dsh-app-host` resolves to that root and whose package.json is a HanaMesh
+ * profile manifest. Ancestors of a real path are real, so a symlinked store path can never be
+ * returned — only the profile that links it.
+ */
+export async function inferProfileDir(moduleUrl){
+  const root=await packageRoot(moduleUrl);if(!root)return undefined;
+  let dir=dirname(root);
+  for(;;){
+    const linked=await realpath(join(dir,'node_modules',...PACKAGE_NAME.split('/'))).catch(()=>undefined);
+    if(linked===root&&isHanameshProfileManifest(await json(join(dir,'package.json'))))return dir;
+    const parent=dirname(dir);if(parent===dir)return undefined;dir=parent;
+  }
+}
+
+/** The DSH CLI that started this process — `argv[1]` only when it IS `@deepseek-ai/dsh/lib/bin.js`. */
+export function inferDshBin(argv=process.argv){
+  const candidate=argv?.[1];
+  if(typeof candidate!=='string'||!isAbsolute(candidate))return undefined;
+  return candidate.split(sep).join('/').endsWith(DSH_BIN_SUFFIX)?candidate:undefined;
+}
+
+/** K5: a plain Node process may run library operations with itself; an Electron host must configure `nodeBinary`. */
+export function inferNodeBinary({execPath=process.execPath,versions=process.versions}={}){
+  if(versions.electron!==undefined)return undefined;
+  return typeof execPath==='string'&&isAbsolute(execPath)?execPath:undefined;
+}
+
+/**
+ * Explicit config always wins; every inferred key is named in `inferred` so the caller can log it.
+ * `sources`: undefined → DEFAULT_CATALOG_SOURCES; an explicit array (including `[]`) is kept as is.
+ */
+export async function resolveLibraryLocations(config={},{moduleUrl=import.meta.url,argv=process.argv,execPath=process.execPath,versions=process.versions,nodeBinary}={}){
+  const inferred=[];
+  let profileDir=config.profileDir;if(profileDir===undefined){profileDir=await inferProfileDir(moduleUrl);if(profileDir)inferred.push('profileDir');}
+  let profileName=config.profileName;if(profileName===undefined&&profileDir){profileName=basename(profileDir);inferred.push('profileName');}
+  let dshBin=config.dshBin;if(dshBin===undefined){dshBin=inferDshBin(argv);if(dshBin)inferred.push('dshBin');}
+  let node=nodeBinary;if(node===undefined){node=inferNodeBinary({execPath,versions});if(node)inferred.push('nodeBinary');}
+  let sources=config.sources;if(sources===undefined){sources=structuredClone(DEFAULT_CATALOG_SOURCES);inferred.push('sources');}
+  return{profileDir,profileName,dshBin,nodeBinary:node,sources,inferred};
+}

package/dist/library/routes.js

@@ -0,0 +1,17 @@
+import { randomUUID } from 'node:crypto';
+import { AppHostError, requireCondition } from '../errors.js';
+import { loopbackOrigin } from '../descriptor.js';
+
+/** rc.28 adds `installedPlugins` (GET) and `plugins/install` / `plugins/uninstall` (POST, by package name); every older route is kept. */
+export const LIBRARY_ROUTES=['/hanamesh/library','/hanamesh/library/sources','/hanamesh/library/install','/hanamesh/library/provision','/hanamesh/library/uninstall','/hanamesh/library/events','/hanamesh/library/installedPlugins','/hanamesh/library/plugins/install','/hanamesh/library/plugins/uninstall'];
+async function jsonBody(req){const chunks=[];let total=0;for await(const chunk of req){total+=chunk.length;requireCondition(total<=65_536,'BODY_TOO_LARGE','Request body is too large.',{},413);chunks.push(chunk);}try{return JSON.parse(Buffer.concat(chunks).toString('utf8'));}catch{throw new AppHostError('INVALID_JSON','Malformed JSON.',{},400);}}
+function send(res,status,value){res.writeHead(status,{'content-type':'application/json; charset=utf-8','cache-control':'no-store','x-content-type-options':'nosniff','content-security-policy':"default-src 'none'; frame-ancestors 'none'"});res.end(JSON.stringify(value));}
+export function createLibraryHttpHandler(library,{parentOrigin,authenticate,authorize}){parentOrigin=loopbackOrigin(parentOrigin);return async(req,res)=>{const traceId=randomUUID();try{
+  requireCondition(req.headers.host===new URL(parentOrigin).host,'HOST_DENIED','Unrecognized request host.',{},403);const url=new URL(req.url,parentOrigin),path=url.pathname;requireCondition(LIBRARY_ROUTES.includes(path),'NOT_FOUND','Unknown library route.',{},404);
+  const readOnly=req.method==='GET'&&['/hanamesh/library','/hanamesh/library/sources','/hanamesh/library/events','/hanamesh/library/installedPlugins'].includes(path);requireCondition(readOnly||(req.method==='POST'&&path!=='/hanamesh/library/installedPlugins'),'METHOD_NOT_ALLOWED','Unsupported library method.',{},405);
+  requireCondition(!req.headers.origin||req.headers.origin===parentOrigin,'ORIGIN_DENIED','Unapproved browser origin.',{},403);requireCondition(req.headers['sec-fetch-dest']!=='iframe','FRAME_CONTROL_DENIED','An application frame cannot control the host.',{},403);
+  if(!readOnly)requireCondition(req.headers.origin===parentOrigin&&req.headers['x-hanamesh-client']==='workspace-v1','CSRF_DENIED','Workspace origin and explicit client header are required.',{},403);
+  const subject=await authenticate(req);requireCondition(subject&&typeof subject.principalId==='string','UNAUTHENTICATED','Host authentication is required.',{},401);const input=readOnly?Object.fromEntries(url.searchParams):await jsonBody(req);requireCondition(await authorize(subject,path,input)===true,'FORBIDDEN','Operation is not authorized.',{},403);
+  let result;if(path==='/hanamesh/library'&&readOnly){requireCondition(Object.keys(input).every(key=>['q','category','cursor'].includes(key)),'UNKNOWN_FIELDS','Unknown library parameters.');result=await library.list(input);}else if(path==='/hanamesh/library/sources'&&readOnly)result=library.sources();else if(path==='/hanamesh/library/sources')result=await library.replaceSources(input);else if(path==='/hanamesh/library/install')result=await library.install(input);else if(path==='/hanamesh/library/provision')result=await library.provision(input);else if(path==='/hanamesh/library/uninstall')result=await library.uninstall(input);else if(path==='/hanamesh/library/installedPlugins'){requireCondition(Object.keys(input).length===0,'UNKNOWN_FIELDS','installedPlugins takes no parameters.');result=await library.installedSnapshot();}else if(path==='/hanamesh/library/plugins/install')result=await library.installPlugin(input);else if(path==='/hanamesh/library/plugins/uninstall')result=await library.uninstallPlugin(input);else{requireCondition(Object.keys(input).every(key=>key==='after'),'UNKNOWN_FIELDS','Unknown event parameters.');result=library.events(Number(input.after??0));}
+  send(res,!readOnly&&path!=='/hanamesh/library/sources'?202:200,{...result,traceId});
+}catch(error){const trusted=error instanceof AppHostError;send(res,trusted?error.status:500,{error:{code:trusted?error.code:'INTERNAL_ERROR',message:trusted?error.message:'The operation could not be completed.',...(trusted?{details:error.details}:{})},traceId});}};}

package/dist/library/service.js

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import { AppHostError, requireCondition } from '../errors.js';
+import { loadCatalog, isApplication, itemKind, upgradeAvailable, validateManifestUrl } from './catalog.js';
+import { scanInstalled, scanInstalledPlugins, snapshotProfileDependencies } from './installed.js';
+import { PROTECTED_PACKAGES } from './install.js';
+
+const PACKAGE_NAME=/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const text=(value,max)=>typeof value==='string'&&value.length>0&&value.length<=max;
+const RESTART_STATES=new Set(['installed-not-loaded','uninstalled-not-unloaded']);
+const protectedPackage=name=>PROTECTED_PACKAGES.includes(name);
+
+export function createLibraryService({domain,host,config={},dataRoot,ledgerReader,installer}){
+  const events=[];let sequence=0;let state;const running=new Map();let bootDependencies;
+  const emit=event=>{const value={sequence:++sequence,at:Date.now(),...event};events.push(value);if(events.length>512)events.shift();return value;};
+  // Real sources hold ~10k entries (2026-09-20: market.hanamesh.com 12,121). `/hanamesh/library` keeps its rc.16 default
+  // (`category=hanamesh-app`, backward compatible); the rc.28 market page asks for `category=''` (everything) explicitly.
+  const catalog=({q='',category='hanamesh-app',cursor}={})=>loadCatalog({fixture:config.fixture,sources:state.sources,fetchImpl:config.fetchImpl,query:q,category,cursor});
+  async function installed(){return config.profileDir?await scanInstalled({profileDir:config.profileDir,host,ledgerReader,dataRoot}):[];}
+  async function installedPlugins(){return config.profileDir?await scanInstalledPlugins({profileDir:config.profileDir,bootDependencies}):[];}
+  async function persist(next){next.revision=state.revision+1;await domain.global.set(next);state=next;}
+  async function operation(type,task){const operationId=randomUUID();emit({type:`library.${type}-started`,operationId});const work=Promise.resolve().then(task).then(result=>{emit({type:`library.${type}-done`,operationId,result});return result;},error=>{emit({type:`library.${type}-failed`,operationId,code:error.code??'LIBRARY_OPERATION_FAILED'});throw error;}).finally(()=>running.delete(operationId));running.set(operationId,work);work.catch(()=>{});return{operationId,status:'started'};}
+  const requireInstaller=(message)=>requireCondition(installer,'LIBRARY_INSTALL_UNAVAILABLE',message,{},503);
+  /** Find one catalog entry by id; a package name narrows the provider query (the catalog has no get-by-id, but `q=<package>` matches exactly). */
+  async function findItem({itemId,packageName}){
+    requireCondition(text(itemId,160),'INVALID_INPUT','itemId is required.');
+    requireCondition(packageName===undefined||(text(packageName,214)&&PACKAGE_NAME.test(packageName)),'INVALID_INPUT','packageName is invalid.');
+    const page=packageName?await catalog({q:packageName,category:''}):await catalog();
+    const item=page.items.find(row=>row.id===itemId&&(packageName===undefined||row.package?.name===packageName));
+    requireCondition(item,'CATALOG_ITEM_MISSING','Catalog item was not found.',{itemId},404);return item;
+  }
+  async function findByPackage(packageName){
+    requireCondition(text(packageName,214)&&PACKAGE_NAME.test(packageName),'INVALID_INPUT','packageName is required.');
+    requireCondition(!protectedPackage(packageName),'PACKAGE_DENIED','The HanaMesh suite is not managed through the market.',{packageName},403);
+    const page=await catalog({q:packageName,category:''});const item=page.items.find(row=>row.package?.registry==='npm'&&row.package?.name===packageName);
+    requireCondition(item,'CATALOG_ITEM_MISSING','The catalog does not list this package.',{packageName},404);return item;
+  }
+  const runningApp=appId=>host.instanceList().some(instance=>instance.appId===appId&&!['stopped','failed','interrupted'].includes(instance.status));
+  return{
+    async init(){state=await domain.global.get();if(state.sources.length===0&&Array.isArray(config.sources)&&config.sources.length){const sources=config.sources.map((source,index)=>({manifestUrl:validateManifestUrl(source.manifestUrl).href,enabled:source.enabled===true||(source.enabled!==false&&index===0)}));requireCondition(sources.filter(source=>source.enabled).length===1,'CATALOG_SOURCE_REQUIRED','Exactly one catalog source must be enabled.');await persist({...state,sources});}
+      // rc.28: the dependency set at boot is the "loaded" baseline for plugin restart states; unreadable → everything counts as loaded.
+      if(config.profileDir){try{bootDependencies=await snapshotProfileDependencies(config.profileDir);}catch{bootDependencies=undefined;}}
+      return this;},
+    async list({q='',category,cursor}={}){requireCondition(typeof q==='string'&&q.length<=200,'INVALID_QUERY','q must be a string of at most 200 characters.');requireCondition(category===undefined||(typeof category==='string'&&category.length<=64&&/^[a-z0-9._:-]*$/.test(category)),'INVALID_QUERY','category is invalid.');requireCondition(cursor===undefined||(typeof cursor==='string'&&cursor.length>0&&cursor.length<=2048),'INVALID_CURSOR','cursor is invalid.');
+      const page=await catalog({q,category,cursor});const installedRows=await installed();const pluginRows=await installedPlugins();
+      const byPackage=new Map([...pluginRows,...installedRows].map(row=>[row.packageName,row]));
+      const items=page.items.map(item=>{const row=byPackage.get(item.package?.name)??null;const kind=itemKind(item);
+        return{...item,kind,application:isApplication(item),installed:row,upgradeAvailable:Boolean(row&&row.version&&row.state!=='uninstalled-not-unloaded'&&upgradeAvailable(item.latestVersion,row.version))};});
+      const categories=[...new Set(page.items.flatMap(item=>item.categories??[]))].sort();
+      return{source:page.source,items,categories,installed:installedRows,plugins:pluginRows,restartRequired:[...pluginRows,...installedRows].some(row=>RESTART_STATES.has(row.state)),page:page.page};},
+    sources(){return{sources:structuredClone(state.sources),revision:state.revision};},
+    async replaceSources(input){requireCondition(Array.isArray(input?.sources)&&input.sources.length<=16,'INVALID_SOURCES','sources must be an array of at most 16 entries.');const sources=input.sources.map(source=>({manifestUrl:validateManifestUrl(source.manifestUrl).href,enabled:source.enabled===true}));requireCondition(sources.length===0||sources.filter(source=>source.enabled).length===1,'CATALOG_SOURCE_REQUIRED','Exactly one catalog source must be enabled.');await persist({...state,sources});return this.sources();},
+    /** `{itemId, packageName?}`: applications and plugins take the same path (`dsh plugin add --save-exact`); also the upgrade path. */
+    async install(input){requireInstaller('Install requires absolute profileDir, nodeBinary, dshBin and profileName.');const item=await findItem(input??{});return await operation('install',()=>installer.install(item));},
+    async provision(input){requireInstaller('Runtime provision is unavailable.');
+      // LIB-PROVISION-INPUT: a missing field is the caller's error (400), not an internal TypeError inside the operation.
+      requireCondition(text(input?.appId,160),'INVALID_INPUT','appId is required.');requireCondition(text(input?.packageName,214)&&PACKAGE_NAME.test(input.packageName),'INVALID_INPUT','packageName is required.');requireCondition(text(input?.runtimeItem,160),'INVALID_INPUT','runtimeItem is required.');
+      const{appId,packageName,runtimeItem}=input;return await operation('provision',()=>installer.provisionRuntime({appId,packageName,runtimeItem}));},
+    async uninstall(input){requireInstaller('Uninstall is unavailable.');
+      requireCondition(text(input?.appId,160),'INVALID_INPUT','appId is required.');requireCondition(text(input?.packageName,214)&&PACKAGE_NAME.test(input.packageName),'INVALID_INPUT','packageName is required.');requireCondition(input.runtimeItem===undefined||text(input.runtimeItem,160),'INVALID_INPUT','runtimeItem is invalid.');
+      const{appId,packageName,runtimeItem}=input;return await operation('uninstall',()=>installer.uninstall({appId,packageName,runtimeItem,running:runningApp(appId)}));},
+    /** rc.28 `{packageName}`: the package must be listed by the enabled catalog; an application package takes the application path. */
+    async installPlugin(input){requireInstaller('Plugin install requires absolute profileDir, nodeBinary, dshBin and profileName.');const item=await findByPackage(input?.packageName);return await operation('install',()=>installer.install(item));},
+    /** rc.28 `{packageName}`: `dsh plugin remove`; an installed application package is routed through the application uninstall (runtime + running check). */
+    async uninstallPlugin(input){requireInstaller('Plugin uninstall is unavailable.');const packageName=input?.packageName;requireCondition(text(packageName,214)&&PACKAGE_NAME.test(packageName),'INVALID_INPUT','packageName is required.');requireCondition(!protectedPackage(packageName),'PACKAGE_DENIED','The HanaMesh suite is not managed through the market.',{packageName},403);
+      const app=(await installed()).find(row=>row.packageName===packageName&&row.appId);
+      if(app)return await operation('uninstall',()=>installer.uninstall({appId:app.appId,packageName,runtimeItem:app.runtimeItem,running:runningApp(app.appId)}));
+      return await operation('uninstall',()=>installer.uninstallPlugin({packageName}));},
+    /** Installed application packages of the profile (empty without `profileDir`); rc.27 binds package names for usage evidence. */
+    installed,
+    /** rc.28: installed plugins (every non-application dependency of the profile) with restart states. */
+    installedPlugins,
+    async installedSnapshot(){const plugins=await installedPlugins(),apps=await installed();return{plugins,apps,restartRequired:[...plugins,...apps].some(row=>RESTART_STATES.has(row.state))};},
+    events(after=0){requireCondition(Number.isSafeInteger(after)&&after>=0,'INVALID_CURSOR','Invalid library event cursor.');return{events:events.filter(event=>event.sequence>after),sequence,operations:[...running.keys()]};},
+    async close(){await Promise.allSettled([...running.values()]);await domain.close();},emit,
+  };
+}