@tiinex/core 0.1.1

package/src/actions/record.actions.js

@@ -0,0 +1,312 @@
+import { isWorkspaceEntrypointArtifact, workspaceEntrypointCapability } from '../workspaces/workspace.entrypointCapability.js';
+import { resolveSchemaCapabilities, CapabilityStatus } from '../schemas/capability.registry.js';
+import { canDiscardLocalDraft, canEditLocalDraft } from '../artifacts/artifact.localDraft.js';
+import { schemaIdForRecord } from '../schemas/schema.identity.js';
+
+export const RECORD_ACTIONS_CONTRACT_ID = 'tiinex.record.actions.v1';
+export const RECORD_ACTION_RESULT_SCHEMA_ID = 'tiinex.record.action.result.v1';
+
+export const RecordActionKind = Object.freeze({
+  open: 'record.open',
+  lineage: 'record.lineage',
+  markdown: 'record.markdown',
+  continue: 'record.continue',
+  reference: 'record.reference',
+  source: 'record.source',
+  share: 'record.share',
+  workspaceOpen: 'record.workspace.open',
+  workspaceMerge: 'record.workspace.merge',
+  editLocal: 'record.local.edit',
+  deleteLocal: 'record.local.delete'
+});
+
+export function presentRecordActions(record = {}, options = {}) {
+  const sourceHref = sourceHrefForRecord(record);
+  const hasMaterialText = Boolean(String(record.markdown || record.summary || record.title || '').trim());
+  const availability = actionAvailabilityForRecord(record, options);
+  const actions = [
+    {
+      id: RecordActionKind.open,
+      label: 'Details',
+      icon: 'open',
+      enabled: true,
+      contract: RECORD_ACTIONS_CONTRACT_ID,
+      capabilityStatus: 'implemented'
+    },
+    {
+      id: RecordActionKind.markdown,
+      label: 'Show markdown',
+      icon: 'markdown',
+      enabled: true,
+      contract: RECORD_ACTIONS_CONTRACT_ID,
+      capabilityStatus: 'implemented'
+    }
+  ];
+  if (availability.continue.enabled && hasMaterialText) {
+    actions.push({
+      id: RecordActionKind.continue,
+      label: 'Continue',
+      icon: 'continue',
+      enabled: true,
+      contract: RECORD_ACTIONS_CONTRACT_ID,
+      produces: RECORD_ACTION_RESULT_SCHEMA_ID,
+      capabilityStatus: availability.continue.status,
+      capabilityReason: availability.continue.reason
+    });
+  }
+  if (availability.reference.enabled) {
+    actions.push({
+      id: RecordActionKind.reference,
+      label: 'Preserve evidence',
+      icon: 'reference',
+      enabled: true,
+      contract: RECORD_ACTIONS_CONTRACT_ID,
+      produces: RECORD_ACTION_RESULT_SCHEMA_ID,
+      capabilityStatus: availability.reference.status,
+      capabilityReason: availability.reference.reason
+    });
+  }
+  if (sourceHref) {
+    actions.push({
+      id: RecordActionKind.source,
+      label: 'Open source',
+      icon: 'source',
+      enabled: true,
+      href: sourceHref,
+      contract: RECORD_ACTIONS_CONTRACT_ID,
+      capabilityStatus: 'implemented'
+    });
+  }
+  if (canEditLocalDraft(record)) {
+    actions.push({
+      id: RecordActionKind.editLocal,
+      label: 'Edit local draft',
+      icon: 'edit',
+      enabled: true,
+      contract: RECORD_ACTIONS_CONTRACT_ID,
+      capabilityStatus: 'implemented',
+      capabilityReason: 'Only schema-qualified browser-local drafts can be edited; source identity and provenance are preserved.'
+    });
+  }
+  if (canDiscardLocalDraft(record)) {
+    actions.push({
+      id: RecordActionKind.deleteLocal,
+      label: 'Delete local draft',
+      icon: 'delete',
+      enabled: true,
+      contract: RECORD_ACTIONS_CONTRACT_ID,
+      capabilityStatus: 'implemented',
+      capabilityReason: 'Only browser-local draft/session material is removed; source material is not mutated.'
+    });
+  }
+  actions.push({
+    id: RecordActionKind.share,
+    label: 'Share artifact',
+    icon: 'shareNodes',
+    enabled: true,
+    contract: RECORD_ACTIONS_CONTRACT_ID,
+    capabilityStatus: 'implemented'
+  });
+  const workspaceCapability = workspaceEntrypointCapability(record);
+  if (workspaceCapability.open) {
+    actions.push({
+      id: RecordActionKind.workspaceOpen,
+      label: 'Open',
+      icon: 'workspace',
+      enabled: true,
+      contract: RECORD_ACTIONS_CONTRACT_ID,
+      capabilityStatus: 'implemented',
+      capabilityReason: 'workspace entrypoint capability allows this artifact to become the active workspace context'
+    });
+  }
+  if (workspaceCapability.merge) {
+    actions.push({
+      id: RecordActionKind.workspaceMerge,
+      label: 'Merge',
+      icon: 'continue',
+      enabled: true,
+      contract: RECORD_ACTIONS_CONTRACT_ID,
+      capabilityStatus: 'implemented',
+      capabilityReason: 'workspace entrypoint capability allows this artifact to merge into the current workspace context'
+    });
+  }
+  return Object.freeze(actions);
+}
+
+export function actionAvailabilityForRecord(record = {}, options = {}) {
+  const schemaId = schemaIdForRecord(record);
+  const resolution = resolveSchemaCapabilities({ schemaId });
+  const fallbackUsed = Boolean(resolution.fallbackUsed || resolution.descriptor?.resolution?.fallbackUsed);
+  const actions = resolution.descriptor?.actions || {};
+  return Object.freeze({
+    schemaId,
+    moduleId: resolution.descriptor?.moduleId || '',
+    fallbackUsed,
+    continue: actionAvailability(actions.continue, { fallbackUsed, action: RecordActionKind.continue }),
+    reference: actionAvailability(actions.reference, { fallbackUsed, action: RecordActionKind.reference })
+  });
+}
+
+function actionAvailability(capability = {}, { fallbackUsed = false, action = '' } = {}) {
+  const status = capability?.status || CapabilityStatus.unavailable;
+  const implemented = status === CapabilityStatus.implemented && !fallbackUsed;
+  return Object.freeze({
+    action,
+    enabled: implemented,
+    status,
+    reason: fallbackUsed ? 'root fallback does not expose schema-specific create transitions' : (capability?.reason || 'schema action unavailable')
+  });
+}
+
+export function isRemovableLocalDraftRecord(record = {}) { return canDiscardLocalDraft(record); }
+
+export function isWorkspaceRecord(record = {}) {
+  return isWorkspaceEntrypointArtifact(record);
+}
+
+
+export function sourceHrefForRecord(record = {}) {
+  const source = record.source || {};
+  const adapterId = String(source.adapterId || '').trim();
+  if (adapterId !== 'github') return '';
+  const sourceUrl = firstGithubBrowseHref(
+    record.sourceTarget?.browseUrl,
+    record.sourceTarget?.sourceUrl,
+    record.sourceTarget?.rawUrl,
+    record.snapshot?.sourceUrl,
+    record.snapshot?.rawUrl,
+    record.snapshot?.target?.canonicalUrl,
+    record.recoveredFromUrl,
+    record.browseUrl,
+    record.sourceUrl,
+    record.rawUrl
+  );
+  if (sourceUrl) return sourceUrl;
+  const socialHref = firstGithubSocialHref(record.sourceTarget?.inputTarget, record.snapshot?.target?.canonicalUrl);
+  if (socialHref) return socialHref;
+  const repo = String(source.repo || source.config?.repo || '').trim();
+  const ref = String(source.ref || source.config?.ref || source.resolvedRef || source.commit || record.sourceTarget?.ref || record.snapshot?.target?.ref || '').trim();
+  const path = firstNonEmpty(record.sourceTarget?.sourceArtifactPath, record.snapshot?.sourceArtifactPath, record.sourcePath, record.path);
+  if (!repo || !ref || !path) return '';
+  const cleanPath = githubRepoPathFromUrl(path) || String(path || '').trim().replace(/^\/+/, '');
+  if (!cleanPath || isGithubSocialUrl(path) || isSyntheticIssuePath(cleanPath)) return '';
+  return `https://github.com/${repo}/blob/${ref}/${cleanPath}`;
+}
+
+function firstNonEmpty(...items) { return items.map((item) => String(item || '').trim()).find(Boolean) || ''; }
+function firstGithubBrowseHref(...items) {
+  for (const item of items) {
+    const href = githubBrowseHrefFromUrl(item);
+    if (href) return href;
+  }
+  return '';
+}
+function firstGithubSocialHref(...items) { return items.map((item) => String(item || '').trim()).find(isGithubSocialUrl) || ''; }
+function isGithubSocialUrl(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const parts = url.pathname.split('/').filter(Boolean);
+    return (url.hostname === 'github.com' || url.hostname.endsWith('.github.com')) && parts.length >= 4 && (parts[2] === 'issues' || parts[2] === 'discussions' || parts[2] === 'pull');
+  } catch (_) { return false; }
+}
+function githubBrowseHrefFromUrl(value = '') {
+  const raw = String(value || '').trim();
+  if (!/^https:\/\//i.test(raw)) return '';
+  try {
+    const url = new URL(raw);
+    const parts = url.pathname.split('/').filter(Boolean);
+    if (isGithubSocialUrl(raw)) return raw;
+    if ((url.hostname === 'github.com' || url.hostname.endsWith('.github.com')) && parts.length >= 5 && parts[2] === 'blob') return raw;
+    if (url.hostname === 'raw.githubusercontent.com' && parts.length >= 4) {
+      const [owner, repo, ref, ...pathParts] = parts;
+      if (owner && repo && ref && pathParts.length) return `https://github.com/${owner}/${repo}/blob/${ref}/${pathParts.join('/')}`;
+    }
+  } catch (_) {}
+  return raw;
+}
+function githubRepoPathFromUrl(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const parts = url.pathname.split('/').filter(Boolean);
+    if (url.hostname === 'raw.githubusercontent.com' && parts.length >= 4) return parts.slice(3).join('/');
+    if ((url.hostname === 'github.com' || url.hostname.endsWith('.github.com')) && parts.length >= 5 && parts[2] === 'blob') return parts.slice(4).join('/');
+  } catch (_) {}
+  return '';
+}
+function isSyntheticIssuePath(value = '') {
+  const clean = String(value || '').replace(/^\/+/, '');
+  return clean.startsWith('.topics/.github issue sidecars/') || /^\.topics\/\.github\/[^/]+\/[^/]+\/(?:\.issues|\.discussions|\.pulls)\//i.test(clean);
+}
+
+export function actionIsRenderable(action = {}) {
+  const id = String(action?.id || '');
+  return Boolean(action && action.enabled !== false && (id.startsWith('record.transition:') || action.id === RecordActionKind.open || action.id === RecordActionKind.markdown || action.id === RecordActionKind.lineage || action.id === RecordActionKind.share || action.id === RecordActionKind.continue || action.id === RecordActionKind.reference || action.id === RecordActionKind.workspaceOpen || action.id === RecordActionKind.workspaceMerge || action.id === RecordActionKind.editLocal || action.id === RecordActionKind.deleteLocal || action.href));
+}
+
+export function createRecordActionResult(record = {}, actionId = '') {
+  const action = String(actionId || '').trim();
+  if (action === RecordActionKind.continue) return createContinueResult(record);
+  if (action === RecordActionKind.reference) return createEvidencePreservationResult(record);
+  return null;
+}
+
+function createContinueResult(record = {}) {
+  return Object.freeze({
+    schema: RECORD_ACTION_RESULT_SCHEMA_ID,
+    actionId: RecordActionKind.continue,
+    title: `Continue from ${record.title || 'artifact'}`,
+    intent: 'continue-artifact',
+    sourceBoundary: boundaryForRecord(record),
+    text: continuationCapsule(record)
+  });
+}
+
+function createEvidencePreservationResult(record = {}) {
+  return Object.freeze({
+    schema: RECORD_ACTION_RESULT_SCHEMA_ID,
+    actionId: RecordActionKind.reference,
+    title: `Preserve evidence from ${record.title || 'artifact'}`,
+    intent: 'preserve-evidence-from-selected-record',
+    sourceBoundary: boundaryForRecord(record),
+    text: evidencePreservationCapsule(record)
+  });
+}
+
+function boundaryForRecord(record = {}) {
+  const source = record.source || {};
+  if (source.adapterId === 'github') return 'source-backed github material';
+  if (source.adapterId === 'local' || source.kind === 'local-session') return 'browser-local session material; no GitHub provenance inferred';
+  return 'explicit record boundary';
+}
+
+function evidencePreservationCapsule(record = {}) {
+  const lines = [
+    '# Tiinex Evidence Preservation',
+    '',
+    `Title: ${record.title || 'Untitled artifact'}`,
+    `Record ID: ${record.id || 'unassigned'}`,
+    `Kind: ${record.kind || 'artifact'}`,
+    `Boundary: ${boundaryForRecord(record)}`,
+    '',
+    'Semantics: preserves the selected record as bounded evidence. This is not the PoC cross-artifact Reference relation.'
+  ];
+  if (record.path) lines.push(`Path: ${record.path}`);
+  if (record.source?.label) lines.push(`Source: ${record.source.label}`);
+  if (record.summary) lines.push('', 'Summary:', record.summary);
+  return lines.join('\n');
+}
+
+function continuationCapsule(record = {}) {
+  const body = String(record.markdown || record.summary || '').trim();
+  const excerpt = body.length > 1800 ? `${body.slice(0, 1800)}\n…` : body;
+  return [
+    '# Tiinex Continuation Capsule',
+    '',
+    `Continue from: ${record.title || 'Untitled artifact'}`,
+    `Boundary: ${boundaryForRecord(record)}`,
+    record.path ? `Path: ${record.path}` : '',
+    '',
+    'Material:',
+    excerpt || '(No embedded material text.)'
+  ].filter(Boolean).join('\n');
+}

package/src/adapters/adapter.contracts.js

@@ -0,0 +1,143 @@
+export const ADAPTER_DEFINITION_SCHEMA_ID = 'tiinex.adapter.definition.v1';
+export const ADAPTER_RESULT_SCHEMA_ID = 'tiinex.adapter.result.v1';
+export const SOURCE_REGISTRATION_SCHEMA_ID = 'tiinex.source.registration.v1';
+
+export const AdapterAvailability = Object.freeze({
+  available: 'available',
+  deferred: 'deferred',
+  unavailable: 'unavailable'
+});
+
+export const AdapterResultState = Object.freeze({
+  ok: 'ok',
+  partial: 'partial',
+  failed: 'failed',
+  unavailable: 'unavailable'
+});
+
+export const SourceDiscoveryState = Object.freeze({
+  notStarted: 'not-started',
+  deferred: 'deferred',
+  loading: 'loading',
+  loaded: 'loaded',
+  partial: 'partial',
+  failed: 'failed',
+  unavailable: 'unavailable'
+});
+
+export function makeAdapterDefinition(input = {}) {
+  const id = cleanId(input.id || input.adapterId);
+  if (!id) throw new Error('adapter.id.required');
+  const sourceKinds = freezeList(input.sourceKinds);
+  return Object.freeze({
+    schema: ADAPTER_DEFINITION_SCHEMA_ID,
+    id,
+    label: String(input.label || id).trim(),
+    availability: input.availability || AdapterAvailability.available,
+    sourceKinds,
+    capabilities: Object.freeze(Object.assign({
+      registerSource: false,
+      materialize: false,
+      discover: false,
+      resolveAsset: false,
+      openExternal: false,
+      exportMaterial: false,
+      requiresBridge: false
+    }, input.capabilities || {})),
+    configShape: Object.freeze(Object.assign({}, input.configShape || {})),
+    resultShape: Object.freeze(Object.assign({
+      schema: ADAPTER_RESULT_SCHEMA_ID,
+      records: 'array',
+      assets: 'array',
+      workspaceEntries: 'array',
+      errors: 'array',
+      warnings: 'array',
+      diagnostics: 'object',
+      provenance: 'explicit'
+    }, input.resultShape || {})),
+    boundary: String(input.boundary || 'adapter boundary is explicit').trim(),
+    unavailableReason: String(input.unavailableReason || '').trim(),
+    notes: freezeList(input.notes)
+  });
+}
+
+export function makeSourceRegistration(input = {}, adapter = null) {
+  const adapterId = cleanId(input.adapterId || adapter?.id);
+  const sourceKind = String(input.sourceKind || input.kind || adapter?.sourceKinds?.[0] || '').trim();
+  if (!adapterId) throw new Error('source.adapterId.required');
+  if (!sourceKind) throw new Error('source.sourceKind.required');
+  const id = String(input.id || `${adapterId}:${stableSourceKey(input)}`).trim();
+  return Object.freeze({
+    schema: SOURCE_REGISTRATION_SCHEMA_ID,
+    id,
+    adapterId,
+    sourceKind,
+    label: String(input.label || input.repo || input.path || id).trim(),
+    config: Object.freeze(Object.assign({}, input.config || sourceConfigFromLegacyFields(input))),
+    discoveryState: input.discoveryState || SourceDiscoveryState.deferred,
+    count: Math.max(0, Number(input.count || 0)),
+    boundary: String(input.boundary || adapter?.boundary || 'explicit source boundary').trim(),
+    closeable: input.closeable !== false
+  });
+}
+
+export function makeAdapterResult(input = {}) {
+  const records = Array.isArray(input.records) ? input.records.slice() : [];
+  const assets = Array.isArray(input.assets) ? input.assets.slice() : [];
+  const workspaceEntries = Array.isArray(input.workspaceEntries) ? input.workspaceEntries.slice() : [];
+  const errors = Array.isArray(input.errors) ? input.errors.slice() : [];
+  const warnings = Array.isArray(input.warnings) ? input.warnings.slice() : [];
+  const state = input.state || (errors.length && records.length ? AdapterResultState.partial : (errors.length ? AdapterResultState.failed : AdapterResultState.ok));
+  return Object.freeze({
+    schema: ADAPTER_RESULT_SCHEMA_ID,
+    adapterId: cleanId(input.adapterId || ''),
+    sourceId: String(input.sourceId || '').trim(),
+    state,
+    records: Object.freeze(records),
+    assets: Object.freeze(assets),
+    workspaceEntries: Object.freeze(workspaceEntries),
+    errors: Object.freeze(errors),
+    warnings: Object.freeze(warnings),
+    diagnostics: Object.freeze(Object.assign({}, input.diagnostics || {})),
+    okCount: Number(input.okCount ?? records.length),
+    failCount: Number(input.failCount ?? errors.length)
+  });
+}
+
+export function makeUnavailableAdapterResult(adapterId, reason, extra = {}) {
+  return makeAdapterResult({
+    adapterId,
+    state: AdapterResultState.unavailable,
+    errors: [{ code: 'adapter.unavailable', message: String(reason || 'adapter unavailable') }],
+    warnings: extra.warnings || [],
+    diagnostics: Object.assign({ unavailable: true }, extra.diagnostics || {})
+  });
+}
+
+export function adapterSupportsSourceKind(adapter, sourceKind) {
+  return Boolean(adapter && Array.isArray(adapter.sourceKinds) && adapter.sourceKinds.includes(sourceKind));
+}
+
+function cleanId(value) {
+  return String(value || '').trim().toLowerCase().replace(/[^a-z0-9_.:-]+/g, '-').replace(/^-|-$/g, '');
+}
+
+function freezeList(value) {
+  return Object.freeze((Array.isArray(value) ? value : []).map((item) => String(item || '').trim()).filter(Boolean));
+}
+
+function sourceConfigFromLegacyFields(input = {}) {
+  const config = {};
+  for (const key of ['repo', 'repository', 'ref', 'rootPath', 'path', 'url', 'remote']) {
+    if (input[key] !== undefined && input[key] !== null && String(input[key]).trim()) config[key === 'repository' ? 'repo' : key] = input[key];
+  }
+  return config;
+}
+
+function stableSourceKey(input = {}) {
+  return String(input.repo || input.repository || input.path || input.url || input.label || 'source')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_.:/-]+/g, '-')
+    .replace(/^[:/-]+|[:/-]+$/g, '') || 'source';
+}