ultra-builder-pro-cli 5.0.1 → 6.0.0

package/.ultra-template/specs/architecture.md

@@ -1,81 +0,0 @@
-# Architecture Specification
-
-Define accepted system boundaries, authority, runtime paths, operational behavior, and
-implementation constraints. Describe observed architecture before proposed changes.
-
-## Scope
-
-- Repository or system boundary:
-- Product contracts supported:
-- Revision and environments inspected:
-
-## Observed
-
-| Architectural fact | Source or runtime evidence | Consumer or impact |
-|---|---|---|
-| | | |
-
-## Decisions
-
-| Decision | Driver and evidence | Consequence and recovery | Owner |
-|---|---|---|---|
-| | | | |
-
-## Unknowns
-
-| Unknown | Consequence | Blocking | Owner or next check |
-|---|---|---|---|
-| | | | |
-
-## 30 Architecture Context
-
-| Boundary or external system | Responsibility | Inputs and outputs | Trust or authority | Consumers |
-|---|---|---|---|---|
-| | | | | |
-
-Record material quality goals, technical and organizational constraints, data
-sensitivity, permissions, and compliance boundaries with evidence.
-
-## 31 Solution Strategy
-
-| Accepted direction | Existing pattern or constraint | Consequence | Compatibility or recovery |
-|---|---|---|---|
-| | | | |
-
-## 32 Building Blocks and Runtime Paths
-
-| Building block | Responsibility | Authority and contract | Dependencies | Consumers |
-|---|---|---|---|---|
-| | | | | |
-
-| Runtime path | Entry point | State and side effects | Observable result | Failure and recovery |
-|---|---|---|---|---|
-| | | | | |
-
-## Data and State Authority
-
-| State | Authoritative owner | Writers | Readers | Consistency or migration rule |
-|---|---|---|---|---|
-| | | | | |
-
-## 40 Deployment and Operations
-
-| Environment or operation | Entry point | Configuration or migration | Observation | Rollback or recovery |
-|---|---|---|---|---|
-| | | | | |
-
-## 41 Quality Scenarios and Risks
-
-| Trigger and condition | Expected response | Measurement | Failure response | Owner |
-|---|---|---|---|---|
-| | | | | |
-
-| Risk or debt | Evidence | Consequence | Mitigation and verification | Status |
-|---|---|---|---|---|
-| | | | | |
-
-## Product Traceability
-
-| Product requirement | Architecture path | Public seam | Verification evidence |
-|---|---|---|---|
-| | | | |

package/.ultra-template/specs/discovery.md

@@ -1,74 +0,0 @@
-# Discovery Evidence
-
-Record product evidence and accepted decisions. Link to durable sources instead of
-copying provider payloads or research transcripts.
-
-## Scope
-
-- Repository or product boundary:
-- Inspected Git revision and dirty boundary:
-- Decision this evidence must unlock:
-- Freshness boundary:
-
-## Observed
-
-| Fact or current behavior | Evidence reference | Observed at | Affected section |
-|---|---|---|---|
-| | | | |
-
-## Decisions
-
-| Decision | Evidence and rationale | Owner | Affected contract |
-|---|---|---|---|
-| | | | |
-
-## Unknowns
-
-| Unknown | Consequence | Blocking | Owner or next evidence |
-|---|---|---|---|
-| | | | |
-
-## 00 Problem Validation
-
-- Problem and affected actor:
-- Current workaround and consequence:
-- Demand or usage evidence:
-- Accepted problem boundary:
-
-## 01 Opportunity Discovery
-
-| Desired outcome | Opportunity | Evidence | Constraint or dependency |
-|---|---|---|---|
-| | | | |
-
-## 02 Market Assessment
-
-Record only market, regulatory, commercial, or operational facts that affect a
-decision. Include source date, segment, geography, and assumptions when applicable.
-
-## 03 Alternatives
-
-| Current alternative | Evidence | Meaningful difference | Strategy implication |
-|---|---|---|---|
-| | | | |
-
-## 04 Product Strategy
-
-- Intended actors and outcome:
-- Value delivered through observable behavior:
-- Accepted tradeoffs:
-- Explicit constraints or exclusions:
-
-## 05 Assumptions and Validation
-
-| Assumption | Current evidence | Validation signal | Decision rule | Owner |
-|---|---|---|---|---|
-| | | | | |
-
-## Baseline Gaps
-
-Assign stable ids here and cite the repository evidence that exposed each gap.
-
-| Gap id | Category | Status | Evidence | Owner |
-|---|---|---|---|---|
-| | | | | |

package/.ultra-template/specs/product.md

@@ -1,80 +0,0 @@
-# Product Specification
-
-Define accepted product behavior and scope. Keep current behavior distinct from
-proposed behavior; this is not a transcript or task list.
-
-## Scope
-
-- Product or repository boundary:
-- Intended outcome:
-- Explicit non-goals or constraints:
-
-## Observed
-
-| Current behavior or constraint | Evidence reference | Status | Affected requirement |
-|---|---|---|---|
-| | | | |
-
-## Decisions
-
-| Decision | Rationale | Acceptance impact | Owner |
-|---|---|---|---|
-| | | | |
-
-## Unknowns
-
-| Unknown | Blocking | Owner | Resolution evidence |
-|---|---|---|---|
-| | | | |
-
-## 10 Actors and Jobs
-
-| Actor or system | Job and context | Entry point | Constraints | Evidence |
-|---|---|---|---|---|
-| | | | | |
-
-## 11 User Scenarios
-
-| Scenario id | Actor and trigger | Flow | Observable outcome | Failure and recovery | Evidence |
-|---|---|---|---|---|---|
-| | | | | | |
-
-## 20 Behavioral Requirements and Acceptance
-
-### Requirement: pending
-
-- Source scenario or constraint:
-- Preconditions:
-- Action:
-- Observable result:
-- Error behavior and recovery:
-- Verification:
-
-## 21 Capability and Scope Boundary
-
-| Capability | Included requirements | Dependencies | Status and rationale |
-|---|---|---|---|
-| | | | |
-
-Scope status must reflect an explicit decision. Do not infer a reduced product posture.
-
-## 22 Outcomes and Measurements
-
-The accepted project direction and any single North Star outcome or metric live in
-`.ultra/north-star.md`. Record supporting outcomes, measures, and guardrails here; do
-not force one metric when an observable outcome plus guardrails is the honest contract.
-
-| Outcome or guardrail | Definition | Evidence source | Decision use | Owner |
-|---|---|---|---|---|
-| | | | | |
-
-## Documentation Impact
-
-List maintained documents that must stay consistent, or record a specific no-change
-rationale.
-
-## Architecture Traceability
-
-| Requirement | Public seam | Architecture path | Verification evidence |
-|---|---|---|---|
-| | | | |

package/.ultra-template/specs/research-distillate.md

@@ -1,57 +0,0 @@
-# Research Traceability
-
-This file is a navigation and convergence artifact. Do not duplicate the baseline
-specifications' prose.
-
-## Scope
-
-- Baseline or change id:
-- Research workflow id and mode:
-- Repository revision:
-- Coverage dispositions and selected evidence work:
-
-## Observed
-
-| Claim | Evidence reference | Specification anchor |
-|---|---|---|
-| | | |
-
-## Decisions
-
-| Decision | Owner and approval | Specification anchor |
-|---|---|---|
-| | | |
-
-## Unknowns
-
-| Unknown or gap id | Blocking | Owner and revisit condition |
-|---|---|---|
-| | | |
-
-## Source Revisions
-
-| Canonical source | Git blob hash from `git hash-object` | Status |
-|---|---|---|
-| `.ultra/specs/product.md` | | current or stale |
-| `.ultra/specs/architecture.md` | | current or stale |
-| `.ultra/specs/discovery.md` | | current or stale |
-
-## End-to-End Trace
-
-| Problem or constraint | Actor and scenario | Requirement and acceptance | Architecture path | Verification |
-|---|---|---|---|---|
-| | | | | |
-
-## Verification
-
-| Command or observation | Result | Evidence location | Freshness |
-|---|---|---|---|
-| | | | |
-
-## Planning Entry
-
-- Accepted scope and posture:
-- Required references:
-- Blocking gaps:
-- Allowed transitions:
-- Host recommendation and rationale:

package/.ultra-template/tasks.json

@@ -1,4 +0,0 @@
-{
-  "$schema": "ultra-task-ledger-v2",
-  "tasks": []
-}

package/.ultra-template/test-report.json

@@ -1,44 +0,0 @@
-{
-  "$schema": "ultra-test-report-v2",
-  "change_id": null,
-  "task_ids": [],
-  "task_evidence": [],
-  "git_commit": null,
-  "intent_digest": null,
-  "worktree": {
-    "dirty": null,
-    "diff_digest": null
-  },
-  "commands": [],
-  "areas": {
-    "anti_patterns": {"status": "not_run", "evidence_refs": [], "omissions": ["Not yet run"]},
-    "coverage_gaps": {"status": "not_run", "evidence_refs": [], "omissions": ["Not yet run"]},
-    "wiring": {"status": "not_run", "evidence_refs": [], "omissions": ["Not yet run"]},
-    "e2e": {"status": "not_run", "evidence_refs": [], "omissions": ["Not yet run"]},
-    "performance": {"status": "not_run", "evidence_refs": [], "omissions": ["Not yet run"]},
-    "security": {"status": "not_run", "evidence_refs": [], "omissions": ["Not yet run"]}
-  },
-  "review": {
-    "session": null,
-    "packet_digest": null,
-    "admission_digest": null,
-    "subject_digest": null,
-    "execution_mode": null,
-    "finding_schema": "ultra-review-findings-v4",
-    "summary_ref": null,
-    "summary_digest": null,
-    "context_digest": null,
-    "worktree_digest": null,
-    "verdict": "INCOMPLETE",
-    "coverage_refs": [],
-    "limitations": ["Not yet run"]
-  },
-  "verified_seams": [],
-  "findings": [],
-  "omissions": ["Not yet run"],
-  "residual_risks": [],
-  "owner_disposition": [],
-  "passed": false,
-  "run_count": 0,
-  "timestamp": null
-}

package/adapters/_shared/host-profile.cjs

@@ -1,5 +0,0 @@
-'use strict';
-
-// One-cycle compatibility import. The installed Skill owns the live delegation
-// profile so package CLI users and direct Skill callers execute the same contract.
-module.exports = require('../../skills/ultra-delegate/scripts/host-profile.cjs');

package/adapters/grok.js

@@ -1,242 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-
-const {
-  copyHooks,
-  copySkills,
-  inspectPlugin,
-  markManaged,
-  publishManagedTrees,
-  removeManaged,
-  writePluginProvenance,
-} = require('./_shared/plugin-core.cjs');
-const {
-  captureAbsent,
-  ensureDir,
-  isManaged,
-  managedMetadata,
-  pruneCreatedEmpty,
-  removeTree,
-  writeAtomic,
-} = require('./_shared/file-ops.cjs');
-
-const PLUGIN_NAME = 'ultra-builder-pro';
-
-function resolveTarget(ctx = {}) {
-  if (ctx.configDir) return path.resolve(ctx.configDir);
-  const configured = ctx.grokHome || ctx.grokEnv?.GROK_HOME || ctx.env?.GROK_HOME || process.env.GROK_HOME;
-  return configured ? path.resolve(configured) : path.join(ctx.homeDir || os.homedir(), '.grok');
-}
-
-function resolveSourceRoot(ctx = {}) {
-  return path.join(resolveTarget(ctx), '.ubp', 'plugin-sources', PLUGIN_NAME);
-}
-
-function resolvePluginRoot(ctx = {}) {
-  return path.join(resolveTarget(ctx), 'plugins', PLUGIN_NAME);
-}
-
-function resolveRepoRoot(ctx = {}) {
-  return ctx.repoRoot || path.resolve(__dirname, '..');
-}
-
-function assertPluginScope(ctx = {}) {
-  if (ctx.scope === 'local' && !ctx.configDir) {
-    throw new Error('Grok plugins are user-scoped; use global scope or an isolated configDir');
-  }
-}
-
-function hookCommand(name) {
-  return {
-    type: 'command',
-    command: `python3 "\${GROK_PLUGIN_ROOT}/hooks/adapters/grok.py" ${JSON.stringify(name)}`,
-    timeout: 10,
-  };
-}
-
-function buildHooksManifest() {
-  return {
-    description: 'Ultra file-first context sensors and narrow effect protection.',
-    hooks: {
-      SessionStart: [
-        { matcher: 'startup|resume|clear', hooks: [hookCommand('session_context.py')] },
-        { matcher: 'compact', hooks: [hookCommand('compact_context.py')] },
-      ],
-      PreToolUse: [
-        { matcher: 'Write|Edit|Grep|apply_patch', hooks: [hookCommand('mid_workflow_recall.py')] },
-        { matcher: 'Bash', hooks: [hookCommand('block_dangerous_commands.py')] },
-      ],
-      PostToolUse: [
-        { matcher: 'Write|Edit|apply_patch', hooks: [hookCommand('post_edit_guard.py')] },
-      ],
-      PreCompact: [{ matcher: 'manual|auto', hooks: [hookCommand('compact_context.py')] }],
-    },
-  };
-}
-
-function buildStaging(repoRoot, staging, publishedRoot) {
-  const skills = copySkills({ runtime: 'grok', repoRoot, skillRoot: path.join(staging, 'skills') });
-  copyHooks({
-    runtime: 'grok', repoRoot, hookRoot: path.join(staging, 'hooks'),
-    hooksManifest: buildHooksManifest(),
-  });
-  const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
-  writeAtomic(path.join(staging, 'plugin.json'), `${JSON.stringify({
-    name: PLUGIN_NAME,
-    version: pkg.version,
-    description: 'File-first Ultra Builder Pro workflows for Grok Build.',
-    author: { name: pkg.author },
-    homepage: pkg.homepage,
-    repository: pkg.repository?.url || pkg.repository,
-    license: pkg.license,
-  }, null, 2)}\n`);
-  markManaged(staging, { adapter: 'grok', plugin: PLUGIN_NAME, version: pkg.version });
-  writePluginProvenance({
-    adapter: 'grok', repoRoot, stagingRoot: staging, publishedRoot,
-    contracts: {
-      plugin_manifest: { root: 'plugin', path: 'plugin.json' },
-      hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
-      hook_adapter: { root: 'plugin', path: 'hooks/adapters/grok.py' },
-    },
-  });
-  return { skills };
-}
-
-function shouldRunHostCli(ctx = {}) {
-  if (typeof ctx.runHostCli === 'boolean') return ctx.runHostCli;
-  return ctx.scope === 'global' && !ctx.configDir;
-}
-
-function runGrok(ctx, args) {
-  const result = spawnSync(ctx.grokBin || 'grok', args, {
-    encoding: 'utf8', timeout: ctx.hostCliTimeoutMs || 30000,
-    env: { ...process.env, GROK_HOME: resolveTarget(ctx) },
-  });
-  if (result.error) throw result.error;
-  if (result.status !== 0) throw new Error((result.stderr || result.stdout || '').trim() || `grok ${args.join(' ')} failed`);
-  return result.stdout;
-}
-
-function installedPlugin(ctx) {
-  const value = JSON.parse(runGrok(ctx, ['plugin', 'list', '--json']));
-  if (!Array.isArray(value)) throw new Error('grok plugin list --json must return an array');
-  return value.find((entry) => entry?.name === PLUGIN_NAME) || null;
-}
-
-function install(ctx = {}) {
-  assertPluginScope(ctx);
-  const sourceRoot = resolveSourceRoot(ctx);
-  const configRoot = resolveTarget(ctx);
-  const repoRoot = resolveRepoRoot(ctx);
-  const cleanupAbsent = managedMetadata(sourceRoot)?.cleanup_absent
-    || captureAbsent(configRoot, ['.', '.ubp', path.join('.ubp', 'plugin-sources'), 'plugins']);
-  ensureDir(path.dirname(sourceRoot));
-  const staging = fs.mkdtempSync(path.join(path.dirname(sourceRoot), `.${PLUGIN_NAME}-staging-`));
-  const recovery = fs.existsSync(sourceRoot)
-    ? fs.mkdtempSync(path.join(path.dirname(sourceRoot), `.${PLUGIN_NAME}-recovery-`))
-    : null;
-  if (recovery) fs.cpSync(sourceRoot, recovery, { recursive: true });
-  let previousRegistration = null;
-  try {
-    const copied = buildStaging(repoRoot, staging, sourceRoot);
-    markManaged(staging, { cleanup_absent: cleanupAbsent });
-    publishManagedTrees([{ source: staging, target: sourceRoot, label: 'Grok plugin source' }]);
-    if (shouldRunHostCli(ctx)) {
-      runGrok(ctx, ['plugin', 'validate', sourceRoot]);
-      previousRegistration = installedPlugin(ctx);
-      if (previousRegistration) runGrok(ctx, ['plugin', 'uninstall', PLUGIN_NAME, '--confirm', '--keep-data']);
-      runGrok(ctx, ['plugin', 'install', sourceRoot, '--trust']);
-      runGrok(ctx, ['plugin', 'enable', PLUGIN_NAME]);
-      runGrok(ctx, ['plugin', 'details', PLUGIN_NAME]);
-    }
-    if (recovery) removeTree(recovery);
-    return {
-      target: sourceRoot,
-      pluginRoot: sourceRoot,
-      skillRoot: path.join(sourceRoot, 'skills'),
-      hookRoot: path.join(sourceRoot, 'hooks'),
-      copied,
-    };
-  } catch (error) {
-    const rollback = [];
-    try {
-      if (fs.existsSync(sourceRoot)) removeTree(sourceRoot);
-      if (recovery) fs.renameSync(recovery, sourceRoot);
-      if (previousRegistration && shouldRunHostCli(ctx)) {
-        try { runGrok(ctx, ['plugin', 'uninstall', PLUGIN_NAME, '--confirm', '--keep-data']); } catch {}
-        runGrok(ctx, ['plugin', 'install', sourceRoot, '--trust']);
-        if (previousRegistration.enabled !== false) runGrok(ctx, ['plugin', 'enable', PLUGIN_NAME]);
-      }
-    } catch (rollbackError) {
-      rollback.push(rollbackError);
-    }
-    if (fs.existsSync(staging)) removeTree(staging);
-    pruneCreatedEmpty(configRoot, cleanupAbsent);
-    if (rollback.length) throw new AggregateError([error, ...rollback], 'Grok install and rollback failed');
-    throw error;
-  }
-}
-
-function doctor(ctx = {}) {
-  assertPluginScope(ctx);
-  const sourceRoot = resolveSourceRoot(ctx);
-  const report = inspectPlugin({
-    adapter: 'grok', repoRoot: resolveRepoRoot(ctx), pluginRoot: sourceRoot,
-    skillRoot: path.join(sourceRoot, 'skills'), hookRoot: path.join(sourceRoot, 'hooks'),
-    manifestFile: path.join(sourceRoot, 'plugin.json'),
-  });
-  if (shouldRunHostCli(ctx)) {
-    let discovered = false;
-    try {
-      const plugin = installedPlugin(ctx);
-      discovered = !!plugin && plugin.enabled !== false;
-      if (discovered) runGrok(ctx, ['plugin', 'details', PLUGIN_NAME]);
-    } catch {}
-    report.checks.native_registry = { status: discovered ? 'pass' : 'fail' };
-    if (!discovered) report.issues.push({ code: 'GROK_PLUGIN_NOT_REGISTERED' });
-  }
-  report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
-  return report;
-}
-
-function uninstall(ctx = {}) {
-  assertPluginScope(ctx);
-  const sourceRoot = resolveSourceRoot(ctx);
-  const configRoot = resolveTarget(ctx);
-  const cleanupAbsent = managedMetadata(sourceRoot)?.cleanup_absent || [];
-  if (shouldRunHostCli(ctx)) {
-    const plugin = installedPlugin(ctx);
-    if (plugin) runGrok(ctx, ['plugin', 'uninstall', PLUGIN_NAME, '--confirm', '--keep-data']);
-  }
-  const legacy = resolvePluginRoot(ctx);
-  const removedLegacy = fs.existsSync(legacy) && isManaged(legacy)
-    ? removeManaged(legacy, 'legacy Grok plugin')
-    : false;
-  const removedSource = removeManaged(sourceRoot, 'Grok plugin source');
-  const cleaned = pruneCreatedEmpty(configRoot, cleanupAbsent);
-  return {
-    target: sourceRoot,
-    pluginRoot: sourceRoot,
-    removed: {
-      source: removedSource,
-      legacy: removedLegacy,
-    },
-    cleaned,
-  };
-}
-
-module.exports = {
-  name: 'grok',
-  PLUGIN_NAME,
-  buildHooksManifest,
-  resolveTarget,
-  resolvePluginRoot,
-  resolveSourceRoot,
-  install,
-  doctor,
-  uninstall,
-};