@ccslabs/xtend 0.1.0-rc.1

package/xtend-builder/wiring/hydration.d.ts

@@ -0,0 +1,4 @@
+import type { XtendBuilderComponentInput, XtendBuilderRecord } from '../builder-public-types';
+
+export declare const HYDRATION_WIRING_SCHEMA: string;
+export declare function createHydrationWiring(input?: XtendBuilderComponentInput): XtendBuilderRecord;

package/xtend-builder/wiring/hydration.js

@@ -0,0 +1,44 @@
+const {
+  getClassNameFromTag
+} = require('../utils/naming');
+
+const HYDRATION_WIRING_SCHEMA = 'xtend.scaffold.hydration-wiring.v1';
+
+function createHydrationWiring(input = {}) {
+  const tag = String(input.tag || '').trim();
+  const className = input.className || getClassNameFromTag(tag);
+  const fixtureScriptPath = input.fixtureScriptPath || `../../../components/${tag}.js`;
+  const fixtureResultObject = input.fixtureResultObject || `window.__${className}FixtureResult`;
+
+  return {
+    schema: HYDRATION_WIRING_SCHEMA,
+    ok: Boolean(tag),
+    mode: 'dry-run',
+    component: {
+      tag,
+      className,
+      stateAttribute: 'data-xtend-hydrated',
+      lifecycleCallbacks: ['connectedCallback', 'attributeChangedCallback', 'disconnectedCallback'],
+      minimumMethods: ['hydrate', 'render'],
+      rehydrationTrigger: 'attributeChangedCallback'
+    },
+    fixture: {
+      scriptPath: fixtureScriptPath,
+      importMode: 'repo-local-script',
+      resultObject: fixtureResultObject,
+      resultObjectName: fixtureResultObject.replace(/^window\./, ''),
+      cdnAllowed: false,
+      requiredChecks: ['defined', 'hasElement', 'hasShadowRoot', 'hydrated']
+    },
+    reviewRules: [
+      'connectedCallback must reach the same render path as later rehydration.',
+      'attributeChangedCallback must be safe before and after initial connection.',
+      'disconnectedCallback must release scaffold-owned hydration state.'
+    ]
+  };
+}
+
+module.exports = {
+  HYDRATION_WIRING_SCHEMA,
+  createHydrationWiring
+};

package/xtend-builder/wiring/manifest.d.ts

@@ -0,0 +1,5 @@
+import type { XtendBuilderComponentInput, XtendBuilderRecord } from '../builder-public-types';
+
+export declare const MANIFEST_PATCH_PLAN_SCHEMA: string;
+export declare const MANIFEST_WIRING_SCHEMA: string;
+export declare function createManifestWiring(input?: XtendBuilderComponentInput): XtendBuilderRecord;

package/xtend-builder/wiring/manifest.js

@@ -0,0 +1,48 @@
+const MANIFEST_WIRING_SCHEMA = 'xtend.scaffold.manifest-wiring.v1';
+const MANIFEST_PATCH_PLAN_SCHEMA = 'xtend.scaffold.manifest-patch-plan.v1';
+
+function createManifestWiring(input = {}) {
+  const tag = String(input.tag || '').trim();
+  const profiles = Array.isArray(input.profiles) ? input.profiles.slice() : [];
+  const source = input.source || `components/${tag}.js`;
+
+  return {
+    schema: MANIFEST_WIRING_SCHEMA,
+    ok: Boolean(tag),
+    mode: 'dry-run',
+    patchPlan: {
+      schema: MANIFEST_PATCH_PLAN_SCHEMA,
+      operation: 'add-component',
+      tag,
+      source,
+      profiles,
+      importMode: 'repo-local',
+      loaderMode: 'custom-element',
+      hydrationMode: 'custom-element',
+      localImportOnly: true,
+      cdnAllowed: false,
+      requiresReview: true
+    },
+    localImport: {
+      convention: 'repo-relative',
+      source,
+      cdnAllowed: false
+    },
+    loader: {
+      target: 'components/manifest.json',
+      compatibleWith: ['xtend-loader.js', 'customElements.define'],
+      registration: 'custom-element'
+    },
+    reviewRules: [
+      'Manifest patch output must be deterministic for identical scaffold input.',
+      'Generated component imports must stay repo-local unless a later review explicitly allows another source.',
+      'The manifest plan is reviewable in dry-run and applied through the structured manifest patcher in productive writes.'
+    ]
+  };
+}
+
+module.exports = {
+  MANIFEST_PATCH_PLAN_SCHEMA,
+  MANIFEST_WIRING_SCHEMA,
+  createManifestWiring
+};

package/xtend-builder/workflows/README.md

@@ -0,0 +1,47 @@
+# XTend-Scaffold Workflows
+
+Dieser Bereich enthaelt ab `WP-E03-08` lokale Developer-Workflow-Contracts fuer Menschen und AI-Agenten.
+
+## Workflow
+
+`xtend-builder/workflows/developer-workflow.js` erzeugt eine maschinenlesbare Schrittfolge mit Schema `xtend.scaffold.developer-workflow.v1`.
+
+Der Workflow bleibt dry-run-first:
+
+- `component-plan` vor `component-files`
+- `component-files` rendert Dateien und Wiring ohne Schreibzugriff
+- `typing` macht den `.d.ts` Contract und den vorbereiteten XTendRMT-Anschluss sichtbar
+- `preview` macht den Preview-Referenzplan und die lokale Reference-Gate-Anbindung sichtbar
+- `extensions` macht Templating-, Rendering- und Root-Lifecycle-Extension-Punkte sichtbar
+- `verify` macht die passenden Test- und Report-Kommandos sichtbar
+- ab Epic 04 / `WP-E04-07` bindet `rmtCompatibility` Typing, Manifest-Plan, Preview und Extensions als gemeinsamen RMT-Kompatibilitaets-Dry-Run zusammen
+- produktive Generate- oder Write-Modi bleiben spaeteren Workpackages vorbehalten
+
+## Verify-Plan
+
+Der Verify-Plan nutzt Schema `xtend.scaffold.verify-plan.v1`.
+
+Er dokumentiert:
+
+- den lokalen Test-Runner `node scripts/run_xtend_tests.js`
+- die Required Suites aus `xtend-builder/scaffold.config.js`
+- JSON- und Text-Ausgaben
+- den Reportpfad `.xtend-test-results/xtend-test-report.json`
+- den Vollsuite-Pfad `npm test`
+- den RMT-Kompatibilitaets-Minimalgate `node scripts/run_xtend_tests.js rmt-compatibility --json`
+
+## Lokale Einstiege
+
+```bash
+node xtend-builder/scaffold.js workflow --json
+node xtend-builder/scaffold.js verify --json
+node xtend-builder/scaffold.js typing --tag x-example --profile display --json
+node xtend-builder/scaffold.js preview --tag x-example --profile display --json
+node xtend-builder/scaffold.js extensions --tag x-example --profile display --json
+npm run scaffold:workflow
+npm run scaffold:verify
+npm run scaffold:dry-run
+npm run scaffold:typing
+npm run scaffold:preview
+npm run scaffold:extensions
+```

package/xtend-builder/workflows/developer-workflow.d.ts

@@ -0,0 +1,6 @@
+import type { XtendBuilderComponentInput, XtendBuilderWorkflow } from '../builder-public-types';
+
+export declare const DEVELOPER_WORKFLOW_SCHEMA: string;
+export declare const VERIFY_PLAN_SCHEMA: string;
+export declare function createDeveloperWorkflow(input?: XtendBuilderComponentInput): XtendBuilderWorkflow;
+export declare function createVerifyPlan(input?: XtendBuilderComponentInput): XtendBuilderWorkflow;

package/xtend-builder/workflows/developer-workflow.js

@@ -0,0 +1,125 @@
+const config = require('../scaffold.config');
+
+const DEVELOPER_WORKFLOW_SCHEMA = 'xtend.scaffold.developer-workflow.v1';
+const VERIFY_PLAN_SCHEMA = 'xtend.scaffold.verify-plan.v1';
+
+function normalizeExampleInput(input = {}) {
+  return {
+    tag: input.tag || 'x-example',
+    profile: input.profile || input.profiles || 'display',
+    feature: input.feature || input.features || 'state'
+  };
+}
+
+function toCommandParts(command) {
+  return command.split(' ').filter(Boolean);
+}
+
+function createCommand(id, command, purpose, output = 'text') {
+  return {
+    id,
+    command,
+    argv: toCommandParts(command),
+    purpose,
+    output
+  };
+}
+
+function createDeveloperWorkflow(input = {}) {
+  const example = normalizeExampleInput(input);
+  const planCommand = `node xtend-builder/scaffold.js component-plan --tag ${example.tag} --profile ${example.profile} --feature ${example.feature} --json`;
+  const filesCommand = `node xtend-builder/scaffold.js component-files --tag ${example.tag} --profile ${example.profile} --feature ${example.feature} --json`;
+  const typingCommand = `node xtend-builder/scaffold.js typing --tag ${example.tag} --profile ${example.profile} --feature ${example.feature} --json`;
+  const previewCommand = `node xtend-builder/scaffold.js preview --tag ${example.tag} --profile ${example.profile} --feature ${example.feature} --json`;
+  const extensionsCommand = `node xtend-builder/scaffold.js extensions --tag ${example.tag} --profile ${example.profile} --feature ${example.feature} --json`;
+
+  return {
+    schema: DEVELOPER_WORKFLOW_SCHEMA,
+    ok: true,
+    mode: 'dry-run-first',
+    writePolicy: config.tooling.writeStrategy,
+    entryPoints: [
+      createCommand('help', 'node xtend-builder/scaffold.js --help', 'Print the local scaffold command overview.'),
+      createCommand('config', 'node xtend-builder/scaffold.js config --json', 'Inspect scaffold configuration, wiring and test obligations.', 'json'),
+      createCommand('generators', 'node xtend-builder/scaffold.js generators --json', 'Inspect available generator commands.', 'json'),
+      createCommand('templates', 'node xtend-builder/scaffold.js templates --json', 'Inspect template availability.', 'json'),
+      createCommand('component-plan', planCommand, 'Create the dry-run artifact plan for a component.', 'json'),
+      createCommand('component-files', filesCommand, 'Render dry-run file contents plus manifest, hydration and feature wiring.', 'json'),
+      createCommand('typing', typingCommand, 'Inspect the component .d.ts contract and prepared XTendRMT attachment.', 'json'),
+      createCommand('preview', previewCommand, 'Inspect the component preview reference plan and local gate metadata.', 'json'),
+      createCommand('extensions', extensionsCommand, 'Inspect templating, rendering and root-lifecycle extension points.', 'json'),
+      createCommand('verify', 'node xtend-builder/scaffold.js verify --json', 'Inspect local verification commands and required suites.', 'json')
+    ],
+    npmScripts: {
+      scaffold: 'npm run scaffold -- --help',
+      scaffoldWorkflow: 'npm run scaffold:workflow',
+      scaffoldVerify: 'npm run scaffold:verify',
+      scaffoldDryRun: 'npm run scaffold:dry-run',
+      scaffoldTyping: 'npm run scaffold:typing',
+      scaffoldPreview: 'npm run scaffold:preview',
+      scaffoldExtensions: 'npm run scaffold:extensions',
+      test: 'npm test',
+      testReport: 'npm run test:report'
+    },
+    rmtCompatibility: {
+      schema: config.rmtCompatibility.schema,
+      status: config.rmtCompatibility.status,
+      surfaces: config.rmtCompatibility.surfaces.slice(),
+      requiredContracts: config.rmtCompatibility.requiredContracts.slice(),
+      inspectCommands: [typingCommand, previewCommand, extensionsCommand, filesCommand],
+      minimumGate: config.rmtCompatibility.minimumGate,
+      fullGate: config.rmtCompatibility.fullGate,
+      bridgeRuntime: config.rmtCompatibility.bridgeRuntime
+    },
+    reviewChecklist: [
+      'Run component-plan before component-files and keep both outputs reviewable.',
+      'Confirm manifest.localImportOnly and manifest.cdnAllowed before productive work.',
+      'Confirm hydration lifecycle metadata before adding runtime feature code.',
+      'Confirm feature wiring uses canonical xtend.* keys and window.XTend.* API hints.',
+      'Confirm generated .d.ts output includes event/detail types and prepared XTendRMT adapter attachment.',
+      'Confirm rmtCompatibility binds typing, manifest, preview and extension dry-runs before bridge work.',
+      'Confirm preview plans stay repo-local and include a reference-registry entry before productive writes.',
+      'Confirm extension points remain no-op hooks and metadata without runtime imports.',
+      'Run rmt-compatibility and references after scaffold contract changes and npm test before handoff.'
+    ],
+    nextStep: 'Use verify to select the smallest local test gate for the changed surface.'
+  };
+}
+
+function createVerifyPlan(input = {}) {
+  const requestedSuite = input.suite || input.suites || null;
+  const requiredSuites = config.testObligation.requiredSuites.slice();
+  const coreSuites = config.testObligation.coreSuitesForRuntimeChanges.slice();
+  const selectedSuites = requestedSuite ? String(requestedSuite).split(',').map((entry) => entry.trim()).filter(Boolean) : config.workflows.defaultVerifySuites.slice();
+  const suiteCommand = `node scripts/run_xtend_tests.js ${selectedSuites.join(' ')}`;
+  const suiteJsonCommand = `${suiteCommand} --json`;
+
+  return {
+    schema: VERIFY_PLAN_SCHEMA,
+    ok: true,
+    mode: 'verify-plan',
+    runner: config.testObligation.runner,
+    requiredSuites,
+    coreSuitesForRuntimeChanges: coreSuites,
+    selectedSuites,
+    commands: [
+      createCommand('selected', suiteCommand, 'Run the selected local verification suites.'),
+      createCommand('selected-json', suiteJsonCommand, 'Run selected suites with machine-readable JSON output.', 'json'),
+      createCommand('references', 'node scripts/run_xtend_tests.js references --json', 'Run scaffold documentation and reference gates.', 'json'),
+      createCommand('rmt-compatibility', config.rmtCompatibility.minimumGate, 'Run the dedicated RMT compatibility gate.', 'json'),
+      createCommand('component-gates', 'node scripts/run_xtend_tests.js components a11y-hydration', 'Run component and hydration gates for generated artifact contracts.'),
+      createCommand('full', 'npm test', 'Run the full XTend local suite before handoff.'),
+      createCommand('report', config.testObligation.reportCommand, 'Write a machine-readable test report.', 'json-file')
+    ],
+    reportPath: '.xtend-test-results/xtend-test-report.json',
+    exitPolicy: 'All commands that execute tests must exit 0 before the workpackage can be closed.',
+    reviewActors: config.testObligation.reviewActors.slice()
+  };
+}
+
+module.exports = {
+  DEVELOPER_WORKFLOW_SCHEMA,
+  VERIFY_PLAN_SCHEMA,
+  createDeveloperWorkflow,
+  createVerifyPlan
+};

package/xtend-builder/writing/manifest-patcher.d.ts

@@ -0,0 +1,49 @@
+export declare const SCAFFOLD_PATCHERS_SCHEMA: 'xtend.scaffold.patchers.v1';
+export declare const SCAFFOLD_MANIFEST_PATCHER_SCHEMA: 'xtend.scaffold.manifest-patcher.v1';
+export declare const SCAFFOLD_BUILD_REPORT_SCHEMA: 'xtend.scaffold.build-report.v1';
+export declare const DEFAULT_MANIFEST_PATH: 'components/manifest.json';
+export declare const BUILD_REPORT_ROOT: '.xtend-build/component-files/';
+
+export interface XtendManifestPatch {
+  schema: typeof SCAFFOLD_MANIFEST_PATCHER_SCHEMA;
+  patchersSchema: typeof SCAFFOLD_PATCHERS_SCHEMA;
+  operation: string;
+  targetPath: string;
+  tag: string;
+  source: string;
+  previousSource: string | null;
+  decision: 'insert-entry' | 'update-existing-entry' | 'already-current' | string;
+  changed: boolean;
+  existingEntryCount: number;
+  nextEntryCount: number;
+  policies: Record<string, unknown>;
+  diagnostics: Array<Record<string, unknown>>;
+}
+
+export interface XtendManifestPatchResult {
+  ok: boolean;
+  schema: typeof SCAFFOLD_MANIFEST_PATCHER_SCHEMA;
+  errors: string[];
+  manifest: Record<string, string>;
+  patch: XtendManifestPatch | null;
+  entry: Record<string, unknown> | null;
+}
+
+export interface XtendComponentBuildReportResult {
+  ok: boolean;
+  schema: typeof SCAFFOLD_BUILD_REPORT_SCHEMA;
+  errors: string[];
+  report: Record<string, unknown>;
+  entry: Record<string, unknown>;
+}
+
+export declare function normalizeManifestSource(source: string, manifestPath?: string): { ok: true; source: string } | { ok: false; error: string };
+export declare function readManifest(rootDir: string, manifestPath?: string): {
+  ok: boolean;
+  exists: boolean;
+  path: string;
+  manifest: Record<string, string>;
+  errors: string[];
+};
+export declare function createManifestPatchEntry(options?: Record<string, unknown>): XtendManifestPatchResult;
+export declare function createComponentBuildReportEntry(options?: Record<string, unknown>): XtendComponentBuildReportResult;