@givolt/i3-composer-agent 2.3.1 → 2.3.3

package/skills/i3-ui-prototype/scripts/project-registry.cjs

@@ -0,0 +1,126 @@
+'use strict';
+const { fs, path, crypto, hash, assert, json, id, inside, write } = require('./native-files.cjs');
+function paths(project, prototypeId) {
+  const root = fs.realpathSync(path.resolve(project || '.'));
+  assert.ok(fs.statSync(root).isDirectory(), 'Project must be a directory');
+  if (prototypeId !== undefined) id(prototypeId);
+  return { project: root, output: inside(root, 'prototypes'), index: inside(root, 'prototypes/index.json'),
+    legacyIndex: inside(root, '.i3-ui-prototypes.json'), lock: inside(root, 'prototypes/.index.lock'), legacyLock: inside(root, '.i3-ui-prototypes.lock'),
+    ...(prototypeId === undefined ? {} : { directory: inside(root, `prototypes/${prototypeId}`), preparation: inside(root, `prototypes/.preparation/${prototypeId}`), scopeFile: inside(root, `prototypes/.preparation/${prototypeId}/scope.json`) }) };
+}
+function moduleIds(scope = {}) {
+  if (scope.schemaVersion !== undefined) assert.ok([1, 2, 3].includes(scope.schemaVersion), 'Unsupported scope schemaVersion');
+  if (scope.moduleIds === undefined && ![2, 3].includes(scope.schemaVersion)) return [];
+  assert.ok(Array.isArray(scope.moduleIds), 'scope.moduleIds must be an array; use [] for unbound scope');
+  for (const value of scope.moduleIds) assert.ok(typeof value === 'string' && value.length <= 128 && /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value), 'Invalid module identifier in scope.moduleIds; use stable PRD module IDs, not paths or requirement text');
+  return [...new Set(scope.moduleIds)];
+}
+function validate(registry, project) {
+  assert.equal(registry.schemaVersion, 1, 'Invalid project prototype registry version');
+  assert.ok(Array.isArray(registry.prototypes), 'Invalid project prototype registry');
+  const ids = new Set();
+  for (const entry of registry.prototypes) {
+    id(entry.id); assert.ok(!ids.has(entry.id), 'Duplicate prototype ID in registry'); ids.add(entry.id);
+    inside(project, entry.directory);
+    assert.ok(entry.appliesTo === undefined || (Array.isArray(entry.appliesTo) && entry.appliesTo.every(value => typeof value === 'string')), 'Invalid appliesTo array');
+  }
+  return registry;
+}
+function read(project) {
+  const locations = paths(project), modern = fs.existsSync(locations.index), legacy = fs.existsSync(locations.legacyIndex);
+  if (modern && legacy) assert.deepEqual(json(locations.index), json(locations.legacyIndex), 'Conflicting prototype indices; resolve or explicitly migrate before writing');
+  const file = modern || !legacy ? locations.index : locations.legacyIndex;
+  const bytes = fs.existsSync(file) ? fs.readFileSync(file) : null;
+  return { ...locations, file, legacy: !modern && legacy, duplicateLegacy: modern && legacy,
+    bytes, registry: validate(bytes ? JSON.parse(bytes.toString('utf8')) : { schemaVersion: 1, prototypes: [] }, locations.project) };
+}
+function transaction(project, operation, { allowDuplicate = false } = {}) {
+  const initial = read(project);
+  assert.ok(allowDuplicate || !initial.duplicateLegacy, 'Duplicate active indices; explicitly resolve before writing');
+  assert.ok(!fs.existsSync(initial.legacyLock), 'Legacy prototype writer lock is active');
+  const createdOutput = !fs.existsSync(initial.output), locks = [];
+  fs.mkdirSync(initial.output, { recursive: true });
+  const acquire = file => { const fd = fs.openSync(file, 'wx'); locks.push({ file, fd }); };
+  try {
+    acquire(initial.lock);
+    if (initial.legacy || initial.duplicateLegacy) acquire(initial.legacyLock);
+    else assert.ok(!fs.existsSync(initial.legacyLock), 'Legacy prototype writer lock is active');
+    const current = read(project);
+    assert.equal(current.file, initial.file, 'Prototype index location changed while acquiring lock');
+    assert.ok(allowDuplicate || !current.duplicateLegacy, 'Duplicate active indices');
+    return operation({ ...current, save() {
+      const latest = read(project);
+      assert.equal(latest.file, current.file, 'Prototype index location changed');
+      assert.deepEqual(latest.bytes, current.bytes, 'Prototype index changed outside the active writer');
+      validate(current.registry, current.project);
+      write(current.project, path.relative(current.project, current.file).split(path.sep).join('/'), current.registry);
+    } });
+  } finally {
+    for (const { file, fd } of locks.reverse()) { fs.closeSync(fd); fs.unlinkSync(file); }
+    if (createdOutput && fs.existsSync(initial.output) && !fs.readdirSync(initial.output).length) fs.rmdirSync(initial.output);
+  }
+}
+function query(options = {}) {
+  const current = read(options.project), prototypes = current.registry.prototypes;
+  if (options.module !== undefined) assert.ok(typeof options.module === 'string' && options.module.trim(), 'Provide a nonempty module identifier or existing legacy label');
+  const errors = [], invalid = new Set();
+  for (const entry of prototypes) {
+    try {
+      const scopeFile = inside(current.project, `${entry.directory}/inputs/scope.json`);
+      if (fs.existsSync(scopeFile)) {
+        const scope = json(scopeFile);
+        if (scope.schemaVersion === 2 || scope.moduleIds !== undefined) assert.deepEqual(entry.appliesTo || [], moduleIds(scope), 'appliesTo differs from fixed scope.moduleIds; explicitly revise or synchronize the index');
+      }
+    } catch (error) { invalid.add(entry.id); errors.push(`${entry.id}: ${error.message}`); }
+  }
+  const matches = options.module === undefined ? [] : prototypes.filter(entry => !invalid.has(entry.id) && entry.appliesTo?.includes(options.module));
+  return { status: errors.length ? 'failed' : 'checked', index: current.file, legacy: current.legacy, prototypes, errors,
+    matches, unbound: prototypes.filter(entry => !invalid.has(entry.id) && !entry.appliesTo?.length), selection: matches.length > 1 ? 'ambiguous' : matches.length ? 'matched' : 'none', readOnly: true,
+    note: 'Module association does not prove implementation, current verification or human approval.' };
+}
+function withInstanceAssociation(directory, scope, operation) {
+  const parent = path.dirname(path.resolve(directory));
+  if (path.basename(parent) !== 'prototypes' || (scope.schemaVersion !== 2 && scope.moduleIds === undefined)) return operation();
+  const project = path.dirname(parent), current = read(project);
+  if (!current.registry.prototypes.some(entry => path.resolve(project, entry.directory) === path.resolve(directory))) return operation();
+  const appliesTo = moduleIds(scope), metadataFile = inside(directory, 'prototype.json'), before = fs.readFileSync(metadataFile);
+  return transaction(project, store => {
+    const entry = store.registry.prototypes.find(item => path.resolve(project, item.directory) === path.resolve(directory));
+    assert.ok(entry, 'Prototype entry disappeared during revision');
+    try { const result = operation(); entry.appliesTo = appliesTo; store.save(); return result; }
+    catch (error) { write(directory, 'prototype.json', before.toString('utf8')); throw error; }
+  });
+}
+function migrate(options = {}) {
+  assert.ok(options.check === undefined || typeof options.check === 'boolean', '--check must be a boolean flag');
+  const initial = read(options.project);
+  if (!fs.existsSync(initial.legacyIndex)) return { status: 'current', index: initial.index, sideEffects: [] };
+  const original = fs.readFileSync(initial.legacyIndex), digest = hash(original);
+  if (options.expectedDigest !== undefined) assert.equal(options.expectedDigest, digest, 'Legacy index changed since preview');
+  const plan = { source: initial.legacyIndex, destination: initial.index, sourceDigest: digest, prototypes: initial.registry.prototypes.length };
+  if (options.check) return { status: 'migration-preview', ...plan, sideEffects: [] };
+  return transaction(options.project, store => {
+    assert.deepEqual(fs.readFileSync(store.legacyIndex), original, 'Legacy index changed during migration');
+    const folder = inside(store.project, `prototypes/.migration/index-${crypto.randomUUID()}`);
+    fs.mkdirSync(folder, { recursive: true });
+    const backup = inside(folder, 'legacy-index.json'), temp = inside(store.project, `prototypes/.index-${crypto.randomUUID()}.tmp`);
+    fs.writeFileSync(backup, original, { flag: 'wx' });
+    write(folder, 'source.json', { ...plan, backup, purpose: 'Source snapshot before explicit index migration' });
+    let created = false;
+    try {
+      if (!fs.existsSync(store.index)) {
+        fs.writeFileSync(temp, original, { flag: 'wx' });
+        try { fs.linkSync(temp, store.index); created = true; }
+        finally { if (fs.existsSync(temp)) fs.unlinkSync(temp); }
+      } else assert.deepEqual(fs.readFileSync(store.index), original, 'Destination index already exists with different content');
+      assert.deepEqual(fs.readFileSync(backup), original, 'Migration backup mismatch');
+      assert.deepEqual(fs.readFileSync(store.legacyIndex), original, 'Legacy index changed before commit');
+      fs.unlinkSync(store.legacyIndex);
+      return { status: 'migrated', ...plan, backup };
+    } catch (error) {
+      if (created && fs.existsSync(store.index) && fs.readFileSync(store.index).equals(original)) fs.unlinkSync(store.index);
+      throw error;
+    }
+  }, { allowDuplicate: true });
+}
+module.exports = { paths, moduleIds, read, transaction, query, withInstanceAssociation, migrate };

package/skills/i3-ui-prototype/scripts/prototype-dependencies.cjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { checkDesignProvider } = require('./prototype-lib.cjs');
+const { discoverProviderCandidates } = require('./design-provider-discovery.cjs');
+const { resolveLocations, scopeBases, toolCandidates } = require('./prototype-locations.cjs');
+
+function skillAt(project, name, options = {}) {
+  const context = resolveLocations({ ...options, project });
+  const candidates = scopeBases(context).map(([root, scope]) => [path.join(root, 'skills', name), `${scope}-skill`]);
+  const legacyConfig = (options.env || process.env).CODEBUDDY_CONFIG_DIR;
+  if (context.host === 'codebuddy' && legacyConfig) candidates.push([path.resolve(legacyConfig, 'skills', name), 'global-skill']);
+  const found = candidates.find(([root]) => fs.existsSync(path.join(root, 'SKILL.md')));
+  return found ? { availability: 'available', root: found[0], source: found[1], invocationVerified: false }
+    : { availability: 'missing', searched: candidates.map(([root]) => root), invocationVerified: false };
+}
+function antdvTool(project, options = {}) {
+  const candidates = toolCandidates(resolveLocations({ ...options, project }), options);
+  const found = candidates.find(item => fs.existsSync(item.root));
+  if (!found) return { availability: 'missing', searched: candidates.map(item => item.root), componentVersion: '1.5.3' };
+  const { root, source } = found;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (pkg.name !== '@antdv-next/cli' || typeof pkg.bin?.antdv !== 'string') throw new Error('Unexpected antDv CLI package');
+    const entry = path.resolve(root, pkg.bin.antdv), relative = path.relative(root, entry);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('CLI entry escapes its package');
+    const args = [entry, 'info', 'Table', '--ver', '1.5.2', '--format', 'json'];
+    const result = spawnSync(process.execPath, args, { cwd: project, env: { ...(options.env || process.env), ANTDV_NO_AUTO_REPORT: '1' }, encoding: 'utf8', timeout: 15000, maxBuffer: 5 * 1024 * 1024 });
+    if (result.status !== 0) throw new Error(result.error?.message || result.stderr || 'CLI query failed');
+    const data = JSON.parse(result.stdout);
+    if (!data || data.name !== 'Table' || !Array.isArray(data.props) || data.error) throw new Error('CLI returned no Table knowledge');
+    return { availability: 'available', root, source, entry, version: pkg.version, command: [process.execPath, ...args], knowledgeVersion: '1.5.2', componentVersion: '1.5.3', exactKnowledgeMatch: false,
+      limitation: 'CLI knowledge 1.5.2 is reference only; verify target 1.5.3 package types/source.' };
+  } catch (error) { return { availability: 'unusable', root, source, reason: error.message }; }
+}
+function check(options = {}) {
+  const locations = resolveLocations(options), { project, host, scope } = locations;
+  const roots = scopeBases(locations).map(([base]) => path.join(base, 'skills/ui-ux-pro-max'));
+  const sources = new Map(scopeBases(locations).map(([base, scope]) => [path.join(base, 'skills/ui-ux-pro-max'), `${scope}-skill`]));
+  let discovery;
+  if (options.provider === undefined) {
+    const aliases = { 'gemini-cli': 'gemini', 'claude-code': 'claude' };
+    // Resolve global registrations from home so project-scoped plugins from the
+    // business workspace are never reused by a global installation.
+    discovery = discoverProviderCandidates({ ...options, project: scope === 'global' ? locations.home : project, host: aliases[host] || host });
+    for (const item of discovery.candidates) { roots.push(item.root); if (!sources.has(item.root)) sources.set(item.root, item.source); }
+  }
+  const uiux = checkDesignProvider({ ...options, project, host, ...(options.provider === undefined ? { providerRoots: [...new Set(roots)] } : {}) });
+  if (discovery) {
+    uiux.diagnostics.push(...discovery.diagnostics);
+    if (uiux.root) uiux.source = sources.get(uiux.root) || uiux.source;
+    for (const attempt of uiux.attempts) attempt.source = sources.get(attempt.root) || attempt.source;
+    const failure = ['ambiguous', 'disabled', 'discovery-error'].map(status => discovery.diagnostics.find(item => item.availability === status)).find(Boolean);
+    if (uiux.availability === 'missing' && failure) Object.assign(uiux, { availability: failure.availability, reason: failure.reason });
+  }
+  const scoped = { ...options, host, scope };
+  const antdv = { skill: skillAt(project, 'antdv', scoped), tool: antdvTool(project, scoped) };
+  return { status: 'checked', host, scope, project, locations, uiux, antdv, optional: true, professionalReady: uiux.availability === 'available',
+    invocationVerified: false, note: 'Read-only availability probe; the selected host must discover and actually invoke Skills. No dependency installation, migration or prototype changes.' };
+}
+function parse(argv) {
+  const operation = argv.shift() || 'check', options = {};
+  if (!['check', 'install'].includes(operation)) throw new Error('Use check or install');
+  const flags = new Set(['project', 'host', 'scope', 'skills', 'provider', 'python', 'tool']);
+  while (argv.length) {
+    const key = argv.shift();
+    if (key === '--migrate-tools' && operation === 'install') { options.migrateTools = true; continue; }
+    if (!key.startsWith('--') || !flags.has(key.slice(2)) || !argv[0] || argv[0].startsWith('--')) throw new Error(`Invalid option: ${key}`);
+    options[key.slice(2)] = argv.shift();
+  }
+  return { operation, options };
+}
+async function main(argv = process.argv.slice(2)) {
+  const { operation, options } = parse([...argv]);
+  return operation === 'check' ? check(options) : require('./optional-skill-install.cjs').install(options);
+}
+module.exports = { check, skillAt, antdvTool, parse, main };
+if (require.main === module) main().then(result => process.stdout.write(JSON.stringify(result, null, 2) + '\n'))
+  .catch(error => { process.stderr.write(JSON.stringify({ status: 'failed', errors: [error.message] }) + '\n'); process.exitCode = 1; });

package/skills/i3-ui-prototype/scripts/prototype-hooks.cjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+'use strict';
+// Explicit configuration lifecycle. check is read-only and never invokes the installer.
+const fs=require('node:fs'),path=require('node:path'),os=require('node:os'),assert=require('node:assert/strict');
+const R=require('./codebuddy-registration.cjs'),C=require('./codebuddy-context.cjs'),E=require('./execution-evidence.cjs');
+function context(options) {
+ assert.equal(options.host||'codebuddy','codebuddy','A+B supports CodeBuddy only');
+ const project=fs.realpathSync(path.resolve(options.project||'.')),scope=options.scope;
+ assert.ok(['project','global'].includes(scope),'Specify project or global installation scope');
+ const base=scope==='project'?path.join(project,'.codebuddy'):C.globalBase(options);
+ const recordText=R.fileIO.read(path.join(base,'state/i3-prototype/installation.json'));
+ const record=recordText?JSON.parse(recordText):null;
+ const unified=path.join(base,'i3-composer-agent/hooks/i3-prototype.cjs');
+ const scriptPath=options.entryPath||(fs.existsSync(unified)?unified:path.join(base,'skills/i3-ui-prototype/scripts/hosts/codebuddy.cjs'));
+ return {project,scope,base,record,scriptPath};
+}
+function prepare(options,runtime={}) {
+ const current=runtime.current||context(options),readText=runtime.readText||R.fileIO.read,action=options.action||'keep';
+ assert.ok(['keep','enable','disable'].includes(action),'Invalid Hook configuration action');
+ if(['keep','disable'].includes(action)&&!current.record){
+  if(action==='disable'){const settings=R.config(readText(path.join(current.base,'settings.json')));assert.ok(!Object.values(settings.hooks||{}).flat().some(g=>g.hooks.some(h=>h.command?.includes(R.OWNER))),'Unknown owned-looking Hook has no ownership record; preserve it for review');}
+  return {summary:{status:'not-enabled',scope:current.scope,changed:false},unchanged:true};
+ }
+ const product=options.product||current.record?.product;assert.ok(['ide','cli'].includes(product),'Use --codebuddy-product ide or cli when enabling Hooks');
+ if(action!=='disable') {
+  const manifest=readText(path.join(current.base,'.i3-composer-agent.json'));
+  if(manifest)assert.ok(!JSON.parse(manifest).agents?.includes('workbuddy'),'Shared CodeBuddy/WorkBuddy registration cannot safely identify the product; preserve settings and use an exclusive CodeBuddy scope');
+  assert.ok(!options.agents?.includes('workbuddy')||current.scope!=='project','Do not enable CodeBuddy audit in a shared WorkBuddy project target');
+ }
+ const explicit=options.transcriptRoot,roots=explicit==='auto'?[]:explicit?[path.resolve(explicit)]:current.record?.transcriptRoots||[];
+ const mode=explicit?(explicit==='auto'?'auto':'manual'):current.record?.transcriptMode||(roots.length?'manual':'auto');
+ if(action!=='disable') {
+  for(const root of roots){const relative=path.relative(current.project,root);assert.ok(relative==='..'||relative.startsWith('..'+path.sep)||path.isAbsolute(relative),'Native log root must be outside the business project; QA exports are not native provenance');}
+ }
+ const settingsText=readText(path.join(current.base,'settings.json')),settings=R.config(settingsText);
+ if(action!=='disable')assert.ok(!settings.disableAllHooks&&!settings.allowManagedHooksOnly,'Host policy prevents automatic auditing; preserve the existing policy');
+ return R.plan({action,...current,product,nodePath:process.execPath,scriptDigest:runtime.scriptDigest||C.bundle(options.entrySource||(path.basename(current.scriptPath)==='i3-prototype.cjs'?current.scriptPath:path.join(__dirname,'hosts/codebuddy.cjs'))),currentText:settingsText,
+  transcriptMode:mode,transcriptRoots:roots,productVersion:options.productVersion||current.record?.productVersion||'unreported'});
+}
+function configure(options) {
+ const change=prepare(options);if(change.unchanged||options.preview)return change.summary;
+ return R.apply(change);
+}
+function check(options,runtime={}) {
+ const current=runtime.current||context(options),profile=require('../assets/hosts/codebuddy/profile.json');
+ const result={scope:current.scope,base:current.base,scriptPath:current.scriptPath,filesPresent:fs.existsSync(current.scriptPath),profile:profile.id,nativeValidation:profile.nativeValidation,readOnly:true,sideEffects:[]};
+ if(process.platform==='win32')return {...result,status:'unsupported',reason:'CodeBuddy Hook quoting on Windows has not been validated'};
+ if(!current.record){
+  const settings=R.config(R.fileIO.read(path.join(current.base,'settings.json')));
+  if(Object.values(settings.hooks||{}).flat().some(group=>group.hooks.some(h=>h.command?.includes(R.OWNER))))return {...result,status:'failed',errors:['Unknown prototype Hook registration has no ownership record; preserve it for review']};
+  return {...result,status:result.filesPresent?'files-present':'not-enabled'};
+ }
+ try {
+  const record=(runtime.registration||C.registration)(current.base),effective=(runtime.select||C.select)({project:current.project,product:record.product,home:options.home,env:options.env});
+  Object.assign(result,{product:record.product,productVersion:record.productVersion,registrationDigest:record.registrationDigest,effective:effective?.base===current.base,transcriptRoots:record.transcriptRoots,
+   transcript:{mode:record.transcriptMode||(record.transcriptRoots?.length?'manual':'auto'),status:'awaiting-native-event',invocationVerified:false}});
+  let observation=null;
+  const parent=path.join(current.base,'state/i3-prototype',C.projectKey(current.project));
+  const entries=runtime.entries||[];
+  if(!runtime.entries&&fs.existsSync(parent))for(const name of fs.readdirSync(parent)) {
+   if(!/^[a-f0-9]{24}$/.test(name))continue;
+   const raw=R.fileIO.read(path.join(parent,name,'session.json'));if(!raw)continue;
+   entries.push(...Object.values(JSON.parse(raw).bindings||{}));
+  }
+  for(const entry of entries)if(entry.project===current.project&&entry.registrationDigest===record.registrationDigest&&entry.settingsDigest===record.settingsDigest&&(!observation||entry.lastHook.at>observation.lastHook.at))observation=entry;
+  if(observation) {
+   result.transcript.path=observation.source.path;
+   C.prefix(observation.source.path,observation.source.bytes,observation.source.digest);
+   C.source({session_id:observation.sessionId,transcript_path:observation.source.path},record,current.project);
+   Object.assign(result.transcript,{status:'verified',invocationVerified:true});
+   result.observation={sessionId:observation.sessionId,projectKey:observation.projectKey,runId:observation.runId,event:observation.lastHook.event,at:observation.lastHook.at};
+  }
+  const recent=observation&&Date.now()-Date.parse(observation.lastHook.at)>=0&&Date.now()-Date.parse(observation.lastHook.at)<30*60*1000;
+  return {...result,status:result.effective&&recent?'active':record.product==='cli'?'pending-host-review':'registered',
+   activationScope:'Only the displayed project/session/configuration and adapter bytes; not all projects or business acceptance',
+   next:record.product==='cli'?'Review /hooks in CodeBuddy Code, then use a new session.':'Reload CodeBuddy and verify a real prototype write task.'};
+ }catch(error){if(result.transcript)Object.assign(result.transcript,{status:'unverified',invocationVerified:false});return {...result,status:'failed',errors:[error.message]};}
+}
+function main(argv=process.argv.slice(2)) {
+ const central=[path.resolve(__dirname,'../../../i3-composer-agent/hooks/manage.cjs'),path.resolve(__dirname,'../../../hooks/manage.cjs')].find(file=>fs.existsSync(file));
+ if(central)return require(central).main([...argv,'--groups','prototype']);
+ const options={action:argv.shift()||'check',host:'codebuddy',project:process.cwd()};
+ while(argv.length){const arg=argv.shift();assert.ok(arg.startsWith('--')&&argv[0]&&!argv[0].startsWith('--'),'Hook option needs a value');const key=arg.slice(2).replace(/-([a-z])/g,(_,c)=>c.toUpperCase());assert.ok(['host','scope','project','product','productVersion','transcriptRoot'].includes(key),'Unknown Hook option');options[key]=argv.shift();}
+ return options.action==='check'?check(options):configure(options);
+}
+module.exports={context,globalBase:C.globalBase,prepare,configure,check,main};
+if(require.main===module)try{const result=main();process.stdout.write(JSON.stringify(result,null,2)+'\n');if(result.status==='failed')process.exitCode=1;}catch(error){process.stderr.write(error.message+'\n');process.exitCode=1;}

package/skills/i3-ui-prototype/scripts/prototype-lib.cjs

@@ -5,6 +5,7 @@ const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
 const templateRegistry = require('./template-adapters.cjs').createTemplateRegistry();
 const { discoverProviderCandidates } = require('./design-provider-discovery.cjs');
+const projectRegistry = require('./project-registry.cjs');
 const hash = value => crypto.createHash('sha256').update(value).digest('hex');
 const json = file => JSON.parse(fs.readFileSync(file, 'utf8'));
 function ensure(condition, message) { if (!condition) throw new Error(message); }
@@ -48,17 +49,27 @@ function tokensCss(tokens) {
   return ':root {\n' + entries.map(([key, value]) => `  --${key}: ${value};`).join('\n') + '\n}\n';
 }
 function providerVersion(root) {
+  const receipt = path.join(root, 'UPSTREAM-ORIGIN.json');
+  if (fs.existsSync(receipt)) {
+    try { const source = json(receipt); if (source.packageName === 'ui-ux-pro-max-cli' && typeof source.version === 'string') return source.version; } catch {}
+  }
   for (let folder = root, i = 0; i < 5; i++, folder = path.dirname(folder)) {
     for (const name of ['skill.json', '.claude-plugin/plugin.json', '.codebuddy-plugin/plugin.json', 'package.json']) {
       const file = path.join(folder, name);
-      if (fs.existsSync(file)) { try { const version = json(file).version; if (version) return version; } catch {} }
+      if (fs.existsSync(file)) {
+        try {
+          const metadata = json(file);
+          if (name === 'package.json' && !['ui-ux-pro-max', 'ui-ux-pro-max-cli'].includes(metadata.name)) continue;
+          if (metadata.version) return metadata.version;
+        } catch {}
+      }
     }
   }
   return 'unversioned';
 }
 function queryProvider(root, query, options = {}) {
   const mode = options.stack ? ['--stack', options.stack] : options.designSystem ? ['--design-system'] : ['--domain', options.domain || 'ux'];
-  const run = spawnSync(options.python || 'python3', ['-B', path.join(root, 'scripts/search.py'), query, ...mode, '--json'], { encoding: 'utf8', timeout: 15000, maxBuffer: 5 * 1024 * 1024 });
+  const run = spawnSync(options.python || (process.platform === 'win32' ? 'python' : 'python3'), ['-B', path.join(root, 'scripts/search.py'), query, ...mode, '--json'], { encoding: 'utf8', timeout: 15000, maxBuffer: 5 * 1024 * 1024 });
   ensure(run.status === 0, `UI/UX Pro Max query unavailable: ${run.error?.code || (run.stderr || '').trim().slice(0, 400)}`);
   return JSON.parse(run.stdout);
 }
@@ -85,6 +96,7 @@ function checkDesignProvider(options = {}) {
   return { ...(failure || {}), availability: failure?.availability || 'missing', searched: roots, attempts, diagnostics, reason: failure?.reason || (options.provider ? '指定的 UI/UX Pro Max 技能路径不存在，请核对 --provider' : '当前宿主未发现 UI/UX Pro Max；可安装，或传入宿主实际提供的 --provider 技能路径') };
 }
 function initPrototype(options, registry = templateRegistry) {
+  if (options.framework === 'vue-antdv-next' || options.template === 'admin-list') return require('./native-pilot-lib.cjs').createPrototype(options);
   const project = path.resolve(options.project || '.');
   const id = identifier(options.id);
   const selected = registry.resolve(options.template || registry.defaultId());
@@ -102,11 +114,8 @@ function initPrototype(options, registry = templateRegistry) {
   ensure(fs.existsSync(project) && fs.statSync(project).isDirectory(), 'Project directory does not exist');
   const directory = contained(project, `prototypes/${id}`);
   ensure(!fs.existsSync(directory), 'Prototype already exists / 原型已存在，使用 revise 或另选标识');
-  const lockPath = contained(project, '.i3-ui-prototypes.lock');
-  const lock = fs.openSync(lockPath, 'wx');
-  try {
-  const registryPath = contained(project, '.i3-ui-prototypes.json');
-  const registry = fs.existsSync(registryPath) ? json(registryPath) : { schemaVersion: 1, prototypes: [] };
+  return projectRegistry.transaction(project, store => {
+  const registry = store.registry;
   ensure(registry.schemaVersion === 1 && Array.isArray(registry.prototypes), 'Invalid project prototype registry');
   ensure(!registry.prototypes.some(entry => entry.id === id), 'Prototype registry already contains identifier');
   const preset = selected.preset;
@@ -131,14 +140,15 @@ function initPrototype(options, registry = templateRegistry) {
     fs.renameSync(staging, directory);
     created = true;
     registry.prototypes.push({ id, directory: `prototypes/${id}`, appliesTo: [] });
-    atomicJson(project, '.i3-ui-prototypes.json', registry);
+    store.save();
   } catch (error) { if (created) fs.rmSync(directory, { recursive: true, force: true }); throw error; }
   finally { if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true }); }
   return { status: 'created', directory, template: template.id, expertMode };
-  } finally { fs.closeSync(lock); fs.unlinkSync(lockPath); }
+  });
 }
 function contentManifest(directory, registry = templateRegistry) {
   const metadata = json(contained(directory, 'prototype.json'));
+  if (metadata.schemaVersion === 2) return require('./native-pilot-lib.cjs').manifest(directory);
   const identity = { id: metadata.id, revision: metadata.revision, template: metadata.template, expertMode: metadata.expertMode, artifactKind: metadata.artifactKind };
   for (const field of registry.forInstance(metadata).runtime.identityFields) if (Object.hasOwn(metadata, field)) identity[field] = metadata[field];
   const paths = ['requirements-map.json', 'qa/design-advice.json', ...['app', 'mocks', 'design-system'].flatMap(folder => files(directory, folder))];
@@ -146,6 +156,7 @@ function contentManifest(directory, registry = templateRegistry) {
   return { schemaVersion: 1, revision: metadata.revision, identity, files: entries, digest: hash(JSON.stringify({ identity, files: entries })) };
 }
 function checkPrototype(directory, options = {}, registry = templateRegistry) {
+  if (json(contained(directory, 'prototype.json')).schemaVersion === 2) return require('./native-pilot-lib.cjs').inspect(directory, options);
   const errors = [];
   try {
     const metadata = json(contained(directory, 'prototype.json'));
@@ -164,7 +175,8 @@ function checkPrototype(directory, options = {}, registry = templateRegistry) {
       ensure(requirement.id && !ids.has(requirement.id), 'Requirement identifiers must be unique'); ids.add(requirement.id);
       ensure(requirement.pages?.length && requirement.scenarios?.length && requirement.roles?.length && requirement.actions?.length, `Incomplete business mapping: ${requirement.id}`);
     }
-    const runtimeFiles = selected.runtime.requiredFiles;
+    const runtimeFiles = [...selected.runtime.requiredFiles];
+    if (metadata.runtime?.offlineVersion === 1) runtimeFiles.push('app/offline.js');
     for (const file of ['app/index.html', 'app/tokens.css', 'app/config.json', 'design-system/MASTER.md', 'design-system/tokens.json', ...runtimeFiles]) contained(directory, file) && ensure(fs.existsSync(path.join(directory, file)), `Missing resource: ${file}`);
     const browserFiles = files(directory, 'app').filter(file => /\.(?:html|mjs|js|css)$/.test(file) && !selected.runtime.excludedBrowserPrefixes.some(prefix => file.startsWith(prefix)));
     for (const file of browserFiles) {
@@ -179,7 +191,7 @@ function checkPrototype(directory, options = {}, registry = templateRegistry) {
     const manifest = contentManifest(directory, registry);
     if (metadata.expertMode === 'professional' && options.acceptance) {
       const advice = json(contained(directory, 'qa/design-advice.json'));
-      ensure(advice.provider?.digest && advice.records.some(record => ['adopted', 'adjusted'].includes(record.decision) && record.query && record.resultIdentity && record.rationale && record.verification), 'Professional advice has not been verified and adopted');
+      ensure(advice.provider?.digest && advice.records.length && advice.records.every(record => ['adopted', 'adjusted', 'rejected', 'no-match'].includes(record.decision) && record.query && record.resultIdentity && record.rationale && record.verification), 'Professional advice has not been queried and reviewed');
     }
     if (options.acceptance) {
       const evidence = json(contained(directory, 'qa/browser.json'));
@@ -193,6 +205,7 @@ function checkPrototype(directory, options = {}, registry = templateRegistry) {
   } catch (error) { errors.push(error.message); return { status: 'failed', errors }; }
 }
 function freezeBaseline(directory, confirmation, registry = templateRegistry) {
+  if (json(contained(directory, 'prototype.json')).schemaVersion === 2) return require('./native-pilot-lib.cjs').confirmBaseline(directory, confirmation);
   const current = contentManifest(directory, registry);
   ensure(confirmation.revision === current.revision && confirmation.digest === current.digest, 'Human confirmation must match current changed content / 确认版本及内容必须一致');
   ensure(confirmation.reviewer?.trim() && confirmation.statement?.trim() && confirmation.source?.trim(), 'Explicit human confirmation / 人类确认 required');
@@ -213,12 +226,16 @@ function freezeBaseline(directory, confirmation, registry = templateRegistry) {
     const metadata = json(contained(directory, 'prototype.json'));
     metadata.review = { status: 'approved', revision: current.revision, digest: current.digest, source: confirmation.source };
     metadata.verification = { status: 'passed', digest: current.digest };
-    if (metadata.expertMode === 'professional') metadata.expert.status = 'used';
+    if (metadata.expertMode === 'professional') {
+      const advice = json(contained(directory, 'qa/design-advice.json'));
+      metadata.expert.status = advice.records.some(record => ['adopted', 'adjusted'].includes(record.decision)) ? 'used' : advice.records.every(record => record.decision === 'no-match') ? 'no-match' : 'reviewed';
+    }
     atomicJson(directory, 'prototype.json', metadata);
   } finally { if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true }); }
   return current;
 }
 function compareBaseline(directory, registry = templateRegistry) {
+  if (json(contained(directory, 'prototype.json')).schemaVersion === 2) return require('./native-pilot-lib.cjs').compareBaseline(directory);
   if (!fs.existsSync(contained(directory, 'baseline.json'))) return { status: 'no-baseline', changes: [], protectedChanges: [] };
   const baseline = json(contained(directory, 'baseline.json'));
   const snapshot = contained(directory, baseline.directory);
@@ -238,7 +255,8 @@ function compareBaseline(directory, registry = templateRegistry) {
   if (selectionChanged) protectedChanges.push('template-or-expert-mode');
   return { status: changes.length || protectedChanges.length ? 'changed' : 'unchanged', baselineRevision: baseline.revision, currentRevision: current.revision, changes, protectedChanges };
 }
-function revisePrototype(directory, revision) {
+function revisePrototype(directory, revision, options = {}) {
+  if (json(contained(directory, 'prototype.json')).schemaVersion === 2) return require('./native-pilot-lib.cjs').revise(directory, { ...options, revision });
   identifier(revision);
   const metadata = json(contained(directory, 'prototype.json'));
   ensure(revision !== metadata.revision && !fs.existsSync(contained(directory, `baselines/${revision}`)), 'Use a new unused revision identifier');

package/skills/i3-ui-prototype/scripts/prototype-locations.cjs

@@ -0,0 +1,69 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+// Reviewed mirror of i3's installer target table; maintenance tests require byte equality.
+const registry = require('../assets/optional-skills/host-targets.json');
+const aliases = { claude: 'claude-code', gemini: 'gemini-cli', copilot: 'github-copilot' };
+function globalSkillsDir(agent, home, env) {
+  const config = agent.globalSkillsDir;
+  if (!config) return null;
+  let base = home;
+  if (config.base === 'config') base = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(home, '.config');
+  if (config.base === 'env') base = env[config.env]?.trim() || path.join(home, config.fallback);
+  if (config.env === 'CODEBUDDY_CONFIG_DIR' && (!path.isAbsolute(base) || /[\x00\r\n]/.test(base))) throw new Error('CODEBUDDY_CONFIG_DIR must be an absolute safe directory');
+  if (config.alternatives && !fs.existsSync(path.join(home, path.dirname(config.path)))) {
+    const alternative = config.alternatives.find(relative => fs.existsSync(path.join(home, path.dirname(relative))));
+    if (alternative) return path.join(home, alternative);
+  }
+  return path.resolve(base, config.path);
+}
+function installedContext() {
+  const file = path.resolve(__dirname, '../../../.i3-composer-agent.json');
+  if (!fs.existsSync(file)) return {};
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (data.name !== 'i3-composer-agent' || !Array.isArray(data.agents)) throw new Error('Invalid i3 installation context');
+  return { hosts: data.agents, scope: data.scope };
+}
+function resolveLocations(options = {}) {
+  const installed = installedContext();
+  if (!options.host && installed.hosts?.length > 1) throw new Error('Multiple installed hosts; specify --host');
+  const selected = options.host || installed.hosts?.[0] || 'codebuddy';
+  const host = aliases[selected] || selected, scope = options.scope || 'project';
+  const agent = registry.agents.find(item => item.id === host);
+  if (!agent) throw new Error(`Unknown host: ${host}`);
+  if (!['project', 'global'].includes(scope)) throw new Error('Use scope project or global');
+  const project = fs.realpathSync(path.resolve(options.project || '.'));
+  if (!fs.statSync(project).isDirectory()) throw new Error('Project must be a directory');
+  const home = path.resolve(options.home || os.homedir()), env = options.env || process.env;
+  const projectSkills = path.resolve(project, agent.projectSkillsDir), globalSkills = globalSkillsDir(agent, home, env);
+  if (scope === 'global' && !globalSkills) throw new Error(`${agent.label}: project installation only`);
+  const skillsDirectory = scope === 'project' ? projectSkills : globalSkills, base = path.dirname(skillsDirectory);
+  const projectBase = path.dirname(projectSkills), globalBase = globalSkills ? path.dirname(globalSkills) : null;
+  // Some hosts put skills directly in the workspace; tools still get a host directory.
+  const projectToolsBase = projectBase === project ? path.join(project, `.${host}`) : projectBase;
+  const projectKey = `${path.basename(project).replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 32) || 'project'}-${crypto.createHash('sha256').update(project).digest('hex').slice(0, 16)}`;
+  const cacheBase = path.join(scope === 'global' ? globalBase : projectToolsBase, 'cache/i3-prototype');
+  return { host, scope, project, home, skillsDirectory, base, projectSkills, globalSkills,
+    projectBase, globalBase, projectToolsBase, projectKey, cacheDirectory: scope === 'global' ? path.join(cacheBase, projectKey) : cacheBase,
+    toolsDirectory: path.join(scope === 'global' ? globalBase : projectToolsBase, 'tools/i3-prototype') };
+}
+function scopeBases(context) {
+  return context.scope === 'global' ? [[context.globalBase, 'global']] : [[context.projectBase, 'project'], ...(context.globalBase ? [[context.globalBase, 'global']] : [])];
+}
+function toolCandidates(context, options = {}) {
+  if (options.tool !== undefined) {
+    if (!path.isAbsolute(options.tool)) throw new Error('--tool requires an absolute antDv package directory');
+    return [{ root: path.resolve(options.tool), source: 'explicit-tool' }];
+  }
+  return [
+    ...toolBases(context).map(([base, scope]) => ({ root: path.join(base, 'tools/i3-prototype/antdv-cli/node_modules/@antdv-next/cli'), source: `${scope}-tool` })),
+    ...(context.scope === 'project' ? ['.prototype-tools/antdv-cli/node_modules/@antdv-next/cli', '.prototype-tools/node_modules/@antdv-next/cli']
+      .map(relative => ({ root: path.join(context.project, relative), source: 'legacy-project-tool' })) : []),
+  ].filter((item, index, all) => all.findIndex(other => other.root === item.root) === index);
+}
+function toolBases(context) {
+  return context.scope === 'global' ? [[context.globalBase, 'global']] : [[context.projectToolsBase, 'project'], ...(context.globalBase ? [[context.globalBase, 'global']] : [])];
+}
+module.exports = { registry, globalSkillsDir, resolveLocations, scopeBases, toolBases, toolCandidates };

package/skills/i3-ui-prototype/scripts/sync-template.cjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+'use strict';
+const { prepareTemplate, syncTemplate, loadTemplate } = require('./template-contract.cjs');
+try {
+  const args = process.argv.slice(2);
+  const option = name => { const index = args.indexOf(name); return index < 0 ? undefined : args[index + 1]; };
+  let result;
+  if (args.includes('--prepare')) {
+    if (!option('--project')) throw new Error('--prepare requires --project <directory>');
+    const prepared = prepareTemplate({ project: option('--project'), id: option('--id') });
+    result = { status: 'passed', directory: prepared.directory, created: prepared.created, digest: prepared.index.digest };
+  } else {
+    const directory = args.find(arg => !arg.startsWith('--'));
+    if (!directory) throw new Error('Usage: sync-template.cjs <directory> [--check] | --prepare --project <directory> [--id <id>]');
+    const index = args.includes('--check') ? loadTemplate(directory).index : syncTemplate(directory);
+    result = { status: 'passed', templateId: index.templateId, digest: index.digest, bindings: index.bindings.length };
+  }
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }