@tiinex/core 0.1.1

package/src/tooling/portable/adapters/node/handoff.manufacture.js

@@ -0,0 +1,193 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { inferWorkspaceTitle, normalizeAdditionalWorkspaceDescriptors, normalizeTransportRoute, safeWorkspaceToken } from './handoff.manufacture.multiRoot.js';
+import { buildToolingBootstrapTransportFiles, PORTABLE_TOOLING_BOOTSTRAP_MANIFEST_SCHEMA_ID } from './handoff.manufacture.bootstrap.js';
+import { normalizeHandoffCarrierLineage } from '../../handoff/carrierLineage.js';
+import { normalizeHandoffCarrierProfile } from '../../handoff/carrierProfile.js';
+import { enumerateNodeWorkspace, PORTABLE_NODE_WORKSPACE_ENUMERATION_SCHEMA_ID } from './handoff.manufacture.enumeration.js';
+import { preparePackageParentWorkspaceReuse } from './handoff.manufacture.packageParent.js';
+import {
+  assertInside,
+  expandPointerDependencyClosure,
+  normalizeRelativePath,
+  projectManufacturingRequirements,
+  resolveWorkspaceRequirementMaterials
+} from './handoff.manufacture.requirements.js';
+import {
+  expandBoundedParentBoundaryClosure,
+  normalizeWorkspaceScopes,
+  normalizeWorkspaceTargetBindings,
+  projectBoundedWorkspaceMaterialization
+} from './handoff.manufacture.scope.js';
+
+export { buildToolingBootstrapTransportFiles, PORTABLE_TOOLING_BOOTSTRAP_MANIFEST_SCHEMA_ID };
+export { enumerateNodeWorkspace, PORTABLE_NODE_WORKSPACE_ENUMERATION_SCHEMA_ID } from './handoff.manufacture.enumeration.js';
+
+export async function prepareNodeHandoffManufacturingInput(input = {}, options = {}) {
+  const workspaceRoot = path.resolve(String(input.workspaceRoot || input.workspace || '.'));
+  const workspaceId = safeWorkspaceToken(input.workspaceId || path.basename(workspaceRoot) || 'workspace');
+  const requestedWorkspaceTitle = String(input.workspaceTitle || input.title || '').trim();
+  const handoffPath = normalizeRelativePath(input.handoffPath || input.handoff || '');
+  if (!handoffPath) throw new Error('portable.handoff-manufacture.handoff-path.required');
+  const absoluteHandoff = path.resolve(workspaceRoot, handoffPath);
+  assertInside(workspaceRoot, absoluteHandoff, 'portable.handoff-manufacture.handoff-path.outside-workspace');
+  const handoffMarkdownPromise = readFile(absoluteHandoff, 'utf8');
+  const toolingBootstrapPromise = buildToolingBootstrapTransportFiles({
+    delivery: input.toolingBootstrap || input.bootstrapDelivery || 'embedded',
+    runtimeRoot: input.runtimeRoot || options.runtimeRoot,
+    expected: input.expectedToolingBootstrap || null,
+    maxFiles: input.bootstrapMaxFiles || options.bootstrapMaxFiles
+  }).then(
+    (value) => Object.freeze({ value, error: null }),
+    (error) => Object.freeze({ value: null, error })
+  );
+  const enumerationPromise = enumerateNodeWorkspace(workspaceRoot, {
+    workspaceId,
+    workspaceTitle: requestedWorkspaceTitle,
+    sourceMetadata: input.workspaceSource || input.sourceMetadata || {},
+    excludeDirectories: input.excludeDirectories || options.excludeDirectories,
+    maxFiles: input.maxFiles || options.maxFiles
+  });
+  const additionalWorkspaceDescriptors = normalizeAdditionalWorkspaceDescriptors(input.additionalWorkspaces || input.workspaceRoots || input.workspaceDescriptors || []);
+  const seenWorkspaceIds = new Set([workspaceId]);
+  const additionalWorkspaceInputs = additionalWorkspaceDescriptors.map((descriptor) => {
+    const id = safeWorkspaceToken(descriptor.id || descriptor.workspaceId || '');
+    if (!descriptor.id && !descriptor.workspaceId) throw new Error('portable.handoff-manufacture.additional-workspace.id.required');
+    if (seenWorkspaceIds.has(id)) throw new Error(`portable.handoff-manufacture.workspace-id.duplicate:${id}`);
+    seenWorkspaceIds.add(id);
+    if (!descriptor.root && !descriptor.workspaceRoot && !descriptor.path) throw new Error(`portable.handoff-manufacture.additional-workspace.root.required:${id}`);
+    return Object.freeze({
+      descriptor,
+      id,
+      root: path.resolve(String(descriptor.root || descriptor.workspaceRoot || descriptor.path || '')),
+      requestedTitle: String(descriptor.title || descriptor.name || descriptor.workspaceTitle || '').trim()
+    });
+  });
+  const packageParentReuse = preparePackageParentWorkspaceReuse({
+    bundle: input.packageParentBundle || null,
+    currentWorkspaceIds: [...seenWorkspaceIds],
+    parentPackagePath: input.packageParentPath || '',
+    parentPackageSha256: input.packageParentSha256 || ''
+  });
+  const additionalEnumerationsPromise = Promise.all(additionalWorkspaceInputs.map(async ({ descriptor, id, root, requestedTitle }) => {
+    const enumerated = await enumerateNodeWorkspace(root, {
+      workspaceId: id,
+      workspaceTitle: requestedTitle,
+      sourceMetadata: descriptor.source || descriptor.sourceMetadata || {},
+      excludeDirectories: descriptor.excludeDirectories || input.excludeDirectories || options.excludeDirectories,
+      maxFiles: descriptor.maxFiles || input.maxFiles || options.maxFiles
+    });
+    if (enumerated.status !== 'qualified-complete') throw new Error(`portable.handoff-manufacture.workspace-enumeration.${id}.${enumerated.status}`);
+    return Object.freeze({ descriptor, id, root, requestedTitle, enumerated });
+  }));
+
+  const [handoffMarkdown, enumeration, additionalEnumerations] = await Promise.all([
+    handoffMarkdownPromise,
+    enumerationPromise,
+    additionalEnumerationsPromise
+  ]);
+  const handoff = Object.freeze({
+    id: handoffPath,
+    path: handoffPath,
+    semanticStatus: String(input.handoffSemanticStatus || 'unknown'),
+    markdown: handoffMarkdown
+  });
+
+  if (enumeration.status !== 'qualified-complete') throw new Error(`portable.handoff-manufacture.workspace-enumeration.${enumeration.status}`);
+  const workspaceTitle = requestedWorkspaceTitle || inferWorkspaceTitle(enumeration) || workspaceId;
+  const primaryMaterialization = Object.freeze({ ...enumeration.materialization, title: workspaceTitle });
+  const workspaceMaterializations = [primaryMaterialization];
+  const workspaceEnumerations = [Object.freeze({ id: workspaceId, root: workspaceRoot, evidence: enumeration.evidence })];
+  const workspaceRuntimeById = new Map([[workspaceId, Object.freeze({ id: workspaceId, root: workspaceRoot, enumeration })]]);
+  for (const { id, root, requestedTitle, enumerated } of additionalEnumerations) {
+    const title = requestedTitle || inferWorkspaceTitle(enumerated) || id;
+    workspaceMaterializations.push(Object.freeze({ ...enumerated.materialization, title }));
+    workspaceEnumerations.push(Object.freeze({ id, root, evidence: enumerated.evidence }));
+    workspaceRuntimeById.set(id, Object.freeze({ id, root, enumeration: enumerated }));
+  }
+  for (const inherited of packageParentReuse.inherited || []) {
+    const id = safeWorkspaceToken(inherited.id || inherited.enumeration?.materialization?.id || '');
+    if (!id || workspaceRuntimeById.has(id)) throw new Error(`portable.handoff-manufacture.package-parent.workspace-precedence.invalid:${id || 'unresolved'}`);
+    const inheritedEnumeration = inherited.enumeration;
+    workspaceMaterializations.push(inheritedEnumeration.materialization);
+    workspaceEnumerations.push(Object.freeze({ id, root: '', evidence: inheritedEnumeration.evidence, provider: 'qualified-package-parent-workspace' }));
+    workspaceRuntimeById.set(id, Object.freeze({ id, root: '', enumeration: inheritedEnumeration, provider: 'qualified-package-parent-workspace' }));
+  }
+  const transportRoutes = Object.freeze([...(input.transportRoutes || input.handoffRoutes || [])].map((route) => normalizeTransportRoute(route, workspaceId)).filter(Boolean));
+  const workspaceTargets = mergeWorkspaceTargetBindings(normalizeWorkspaceTargetBindings({
+    primaryWorkspaceId: workspaceId,
+    primaryTargetPath: input.workspaceTargetPath || input.workspaceArtifactPath || '',
+    explicitBindings: input.workspaceTargets || input.workspaceTargetBindings || [],
+    additionalWorkspaceDescriptors
+  }), packageParentReuse.workspaceTargets || []);
+  const workspaceScopes = normalizeWorkspaceScopes(input.workspaceScopes || input.workspaceScopeBindings || []);
+  for (let index = 0; index < workspaceMaterializations.length; index += 1) {
+    const materialization = workspaceMaterializations[index];
+    const scope = workspaceScopes.get(String(materialization.id || '')) || null;
+    if (!scope || scope.coverage !== 'bounded') continue;
+    const targets = workspaceTargets.filter((item) => String(item.workspaceId || '') === String(materialization.id || ''));
+    if (targets.length !== 1) throw new Error(`portable.handoff-manufacture.workspace-scope.target-${targets.length ? 'ambiguous' : 'required'}:${materialization.id}`);
+    workspaceMaterializations[index] = projectBoundedWorkspaceMaterialization(materialization, scope, targets[0].path);
+  }
+
+  const routeSpecs = transportRoutes.length ? transportRoutes : Object.freeze([{ workspaceId, path: handoffPath }]);
+  let requirements = await projectManufacturingRequirements({ handoff, workspaceId, handoffPath, routeSpecs, workspaceRuntimeById });
+  let materials = await resolveWorkspaceRequirementMaterials(requirements, workspaceRuntimeById, input.materialBindings || {});
+  const dependencyClosure = await expandPointerDependencyClosure({ requirements, materials, workspaceRuntimeById, bindings: input.materialBindings || {} });
+  requirements = dependencyClosure.requirements;
+  materials = dependencyClosure.materials;
+  const parentBoundaryClosure = expandBoundedParentBoundaryClosure({ requirements, materials, workspaceMaterializations, workspaceRuntimeById });
+  requirements = parentBoundaryClosure.requirements;
+  materials = parentBoundaryClosure.materials;
+  const toolingBootstrapResult = await toolingBootstrapPromise;
+  if (toolingBootstrapResult.error) throw toolingBootstrapResult.error;
+  const toolingBootstrap = toolingBootstrapResult.value;
+  const orientationBootstrap = input.transportBootstrapContent
+    ? Object.freeze({ present: true, path: String(input.transportBootstrapPath || 'tiinex.package/bootstrap.md'), content: String(input.transportBootstrapContent), mediaType: 'text/markdown' })
+    : Object.freeze({ present: false });
+
+  return Object.freeze({
+    handoff,
+    requirements,
+    workspace: Object.freeze({ id: workspaceId, name: workspaceTitle, title: workspaceTitle, records: Object.freeze([]), assets: Object.freeze([]) }),
+    workspaceMaterializations: Object.freeze(workspaceMaterializations),
+    materials: Object.freeze(materials),
+    recipient: Object.freeze({ referenceTargets: Object.freeze([...(input.referenceTargets || [])].map(String)) }),
+    bootstrap: orientationBootstrap,
+    additionalTransportFiles: toolingBootstrap.files,
+    transportRoutes,
+    workspaceTargets,
+    carrierLineage: normalizeHandoffCarrierLineage(input.carrierLineage || null),
+    carrierProfile: normalizeHandoffCarrierProfile(input.carrierProfile || null),
+    toolingBootstrap: toolingBootstrap.summary,
+    manufacturingEvidence: Object.freeze({
+      enumeration: enumeration.evidence,
+      workspaceEnumerations: Object.freeze(workspaceEnumerations),
+      toolingBootstrap: toolingBootstrap.summary,
+      packageParentWorkspaceReuse: Object.freeze({
+        state: String(packageParentReuse.state || ''),
+        inspectionStatus: String(packageParentReuse.inspectionStatus || ''),
+        inheritedWorkspaceIds: Object.freeze((packageParentReuse.inherited || []).map((item) => String(item.id || ''))),
+        boundary: String(packageParentReuse.boundary || '')
+      }),
+      carrierProjection: Object.freeze({ requestedRoutes: transportRoutes.length || 1, carrierLineage: normalizeHandoffCarrierLineage(input.carrierLineage || null), carrierProfile: normalizeHandoffCarrierProfile(input.carrierProfile || null), boundary: 'Routes are qualified later against packaged workspace bytes; adapter text is not authority.' })
+    }),
+    verifyRoundtrip: input.verifyRoundtrip !== false
+  });
+}
+
+
+function mergeWorkspaceTargetBindings(explicit = [], inherited = []) {
+  const out = [];
+  const seen = new Set();
+  for (const item of [...explicit, ...inherited]) {
+    const workspaceId = String(item?.workspaceId || '').trim();
+    const targetPath = String(item?.path || '').trim();
+    if (!workspaceId || !targetPath) continue;
+    const key = `${workspaceId}\u0000${targetPath}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(Object.freeze({ ...item, workspaceId, path: targetPath }));
+  }
+  return Object.freeze(out);
+}

package/src/tooling/portable/adapters/node/handoff.manufacture.multiRoot.js

@@ -0,0 +1,49 @@
+import { packageFileBytes, sha256Hex, utf8Bytes } from '../../../../export/package.bytes.js';
+export function normalizeAdditionalWorkspaceDescriptors(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.map((entry) => typeof entry === 'string' ? parseWorkspaceDescriptorString(entry) : Object.freeze({ ...(entry || {}) }));
+  if (typeof value === 'string') return value.split(',').map((entry) => entry.trim()).filter(Boolean).map(parseWorkspaceDescriptorString);
+  if (typeof value === 'object') return Object.entries(value).map(([id, descriptor]) => typeof descriptor === 'string' ? Object.freeze({ id, root: descriptor }) : Object.freeze({ id, ...(descriptor || {}) }));
+  return [];
+}
+
+export function normalizeTransportRoute(route, defaultWorkspaceId = '') {
+  if (typeof route === 'string') {
+    const pathValue = normalizeRelativePath(route);
+    return pathValue ? Object.freeze({ workspaceId: String(defaultWorkspaceId || '').trim(), path: pathValue }) : null;
+  }
+  const pathValue = normalizeRelativePath(route?.path || route?.workspaceRelativePath || '');
+  if (!pathValue) return null;
+  const workspaceId = String(route?.workspaceId || route?.workspace || '').trim();
+  if (!workspaceId) throw new Error('portable.handoff-manufacture.route.workspace-id.required');
+  return Object.freeze({ ...route, workspaceId, path: pathValue });
+}
+
+export function safeWorkspaceToken(value = '') {
+  const raw = String(value || '');
+  const token = raw.trim().replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  if (!token) return 'workspace';
+  if (token.length <= 100) return token;
+  return `${token.slice(0, 87)}-${sha256Hex(utf8Bytes(raw)).slice(0, 12)}`;
+}
+
+export function serializableMetadata(value = {}) {
+  const out = {};
+  for (const [key, item] of Object.entries(value || {})) if (typeof item !== 'function' && typeof item !== 'undefined') out[key] = item;
+  return out;
+}
+
+
+export function inferWorkspaceTitle(enumeration = {}) {
+  const entry = (enumeration.materialization?.entries || []).find((item) => normalizeRelativePath(item.path) === 'package.json');
+  if (!entry) return '';
+  try { return String(JSON.parse(new TextDecoder().decode(packageFileBytes(entry))).name || '').trim(); }
+  catch { return ''; }
+}
+function parseWorkspaceDescriptorString(value = '') {
+  const text = String(value || '').trim();
+  const separator = text.indexOf('=');
+  if (separator <= 0) throw new Error('portable.handoff-manufacture.additional-workspace.descriptor.invalid');
+  return Object.freeze({ id: text.slice(0, separator).trim(), root: text.slice(separator + 1).trim() });
+}
+function normalizeRelativePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\/+/, '').split('/').filter((part) => part && part !== '.').join('/'); }

package/src/tooling/portable/adapters/node/handoff.manufacture.packageParent.js

@@ -0,0 +1,130 @@
+import { packageFileBytes, sha256Hex } from '../../../../export/package.bytes.js';
+import { inspectRecipientFacingV2Topology } from '../../handoff/recipientV2.inspect.js';
+import { parseHandoffPackageV1, RECIPIENT_V2_PACKAGE_V1_ROOT_PATH } from '../../handoff/recipientV2.packageV1.js';
+
+export function preparePackageParentWorkspaceReuse(input = {}) {
+  const bundle = input.bundle || null;
+  if (!bundle?.files?.length) return emptyReuse('unavailable');
+  const currentIds = new Set([...(input.currentWorkspaceIds || [])].map(normalizeId).filter(Boolean));
+  const inspection = inspectRecipientFacingV2Topology(bundle);
+  const declared = declaredPackageWorkspaceBindings(bundle, inspection);
+  if (!declared.length) return emptyReuse('unsupported-parent-surface');
+  if (inspection.status !== 'valid') throw new Error('portable.handoff-manufacture.package-parent.workspace-provider.invalid');
+  const missing = declared.filter((item) => !currentIds.has(normalizeId(item.workspaceId)));
+  if (!missing.length) return emptyReuse('not-needed');
+
+  const providerById = new Map((inspection.workspaceByteProvider?.workspaces || []).map((item) => [normalizeId(item.id), item]));
+  const inspectedById = new Map((inspection.workspaces || []).map((item) => [normalizeId(item.workspaceId), item]));
+  const inherited = [];
+  const workspaceTargets = [];
+  for (const binding of missing) {
+    const id = normalizeId(binding.workspaceId);
+    const provider = providerById.get(id);
+    const inspected = inspectedById.get(id);
+    if (!provider || provider.state !== 'qualified' || provider.mode !== 'archive' || provider.materialization?.materialization !== 'complete' || inspected?.coverage !== 'complete') {
+      throw new Error(`portable.handoff-manufacture.package-parent.workspace-provider.unqualified:${id}`);
+    }
+    const targetPath = String(inspected.sourceWorkspaceTargetInnerPath || binding.workspaceArtifactInnerPath || '').trim();
+    if (!targetPath) throw new Error(`portable.handoff-manufacture.package-parent.workspace-target.unresolved:${id}`);
+    inherited.push(buildInheritedEnumeration(provider, {
+      parentPackagePath: input.parentPackagePath || '',
+      parentPackageSha256: input.parentPackageSha256 || '',
+      archivePackagePath: inspected.workspaceArchivePath || binding.snapshotPath || ''
+    }));
+    workspaceTargets.push(Object.freeze({ workspaceId: id, path: targetPath, source: 'qualified-package-parent-workspace' }));
+  }
+  return Object.freeze({
+    state: 'qualified',
+    inherited: Object.freeze(inherited),
+    workspaceTargets: Object.freeze(workspaceTargets),
+    inspectionStatus: inspection.status,
+    missingWorkspaceIds: Object.freeze(missing.map((item) => normalizeId(item.workspaceId))),
+    boundary: 'Exact complete Workspace bytes reused from one independently qualified received package parent. Explicit current Workspace roots take precedence by id; parent-carrier placement and lineage remain non-semantic.'
+  });
+}
+
+function declaredPackageWorkspaceBindings(bundle = {}, inspection = null) {
+  const roots = (bundle.files || []).filter((file) => String(file.path || '') === RECIPIENT_V2_PACKAGE_V1_ROOT_PATH);
+  if (roots.length === 1) {
+    try {
+      const markdown = new TextDecoder('utf-8', { fatal: true }).decode(packageFileBytes(roots[0]));
+      const declared = [...(parseHandoffPackageV1(markdown).workspaces || [])];
+      if (declared.length) return declared;
+    } catch { /* fall through to independently qualified recipient-v2 inspection */ }
+  }
+  if (!inspection || inspection.detected !== true || inspection.status !== 'valid') return [];
+  return (inspection.workspaces || [])
+    .filter((workspace) => String(workspace.coverage || '') === 'complete')
+    .map((workspace) => Object.freeze({
+      workspaceId: String(workspace.workspaceId || ''),
+      workspaceArtifactInnerPath: String(workspace.sourceWorkspaceTargetInnerPath || ''),
+      snapshotPath: String(workspace.workspaceArchivePath || '')
+    }))
+    .filter((workspace) => workspace.workspaceId && workspace.workspaceArtifactInnerPath && workspace.snapshotPath);
+}
+
+function buildInheritedEnumeration(provider = {}, source = {}) {
+  const entries = Object.freeze([...(provider.entries || [])]
+    .map((entry) => Object.freeze({
+      path: String(entry.path || ''),
+      data: entry.data,
+      bytes: Number(entry.bytes || 0),
+      sha256: String(entry.sha256 || ''),
+      mediaType: mediaTypeForPath(entry.path),
+      referenceTarget: String(entry.referenceTarget || '')
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path)));
+  const includedEntries = Object.freeze(entries.map((entry) => Object.freeze({
+    path: entry.path,
+    bytes: entry.bytes,
+    sha256: entry.sha256,
+    referenceTarget: entry.referenceTarget
+  })));
+  const totalBytes = includedEntries.reduce((sum, entry) => sum + entry.bytes, 0);
+  const evidence = Object.freeze({
+    schema: 'tiinex.portable.workspace-completeness-evidence.v1',
+    state: 'qualified',
+    proof: 'qualified-package-parent-workspace-reuse-v1',
+    boundary: 'exact-qualified-parent-carrier-complete-workspace-entry-set',
+    workspaceId: normalizeId(provider.id),
+    entryCount: includedEntries.length,
+    totalBytes,
+    entriesFingerprint: sha256Hex(new TextEncoder().encode(stableJson(includedEntries)))
+  });
+  const materialization = Object.freeze({
+    id: normalizeId(provider.id),
+    title: String(provider.title || provider.id || ''),
+    state: 'complete',
+    source: Object.freeze({
+      kind: 'qualified-package-parent-workspace',
+      workspaceId: normalizeId(provider.id),
+      boundary: '.',
+      parentPackagePath: String(source.parentPackagePath || ''),
+      parentPackageSha256: String(source.parentPackageSha256 || ''),
+      parentWorkspaceArchivePath: String(source.archivePackagePath || ''),
+      authority: 'none'
+    }),
+    completenessEvidence: evidence,
+    entries,
+    includedEntries
+  });
+  return Object.freeze({
+    id: materialization.id,
+    root: '',
+    enumeration: Object.freeze({
+      schema: 'tiinex.portable.package-parent-workspace-enumeration.v1',
+      status: 'qualified-complete',
+      rootBoundary: '.',
+      evidence,
+      materialization
+    })
+  });
+}
+
+function emptyReuse(state) {
+  return Object.freeze({ state, inherited: Object.freeze([]), workspaceTargets: Object.freeze([]), inspectionStatus: '', missingWorkspaceIds: Object.freeze([]), boundary: 'No package-parent Workspace provider reuse was required.' });
+}
+function normalizeId(value = '') { return String(value || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, ''); }
+function mediaTypeForPath(value = '') { const lower = String(value || '').toLowerCase(); if (lower.endsWith('.md')) return 'text/markdown'; if (lower.endsWith('.json')) return 'application/json'; if (/\.(?:m?js|cjs)$/.test(lower)) return 'text/javascript'; if (lower.endsWith('.ts')) return 'text/typescript'; if (lower.endsWith('.css')) return 'text/css'; if (lower.endsWith('.html')) return 'text/html'; if (/\.(?:yml|yaml)$/.test(lower)) return 'text/yaml'; if (lower.endsWith('.txt')) return 'text/plain'; return 'application/octet-stream'; }
+function stableJson(value) { return JSON.stringify(sortJson(value)); }
+function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])])); }