@a5c-ai/kradle 5.0.1-staging.3abdf9534c25

package/src/gitea-service.js

@@ -0,0 +1,173 @@
+import { createGiteaBackend } from './gitea-backend.js';
+
+/**
+ * Gitea service layer that wraps gitea-backend.js for repo code-browsing operations.
+ *
+ * Returns null when Gitea is not configured so call-sites can fall back to mock data.
+ *
+ * @param {{ giteaUrl?: string, token?: string, fetchImpl?: Function }} [options]
+ * @returns {GiteaService|null}
+ */
+export function createGiteaService(options = {}) {
+  const giteaUrl = options.giteaUrl || process.env.KRADLE_GITEA_HTTP_URL;
+  if (!giteaUrl) return null; // Gitea not configured — callers must fall back
+
+  const backend = createGiteaBackend({
+    baseUrl: giteaUrl,
+    token: options.token || process.env.KRADLE_GITEA_TOKEN,
+    fetchImpl: options.fetchImpl || globalThis.fetch,
+  });
+
+  // Low-level fetch helper that bypasses the backend's opinionated error handling
+  // so service methods can gracefully return null on 404 rather than throwing.
+  const root = giteaUrl.replace(/\/$/, '');
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const token = options.token || process.env.KRADLE_GITEA_TOKEN;
+
+  async function rawRequest(path) {
+    if (!fetchImpl) throw new Error('Gitea service requires a fetch implementation');
+    const response = await fetchImpl(`${root}/api/v1${path}`, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+        ...(token ? { Authorization: `token ${token}` } : {}),
+      },
+    });
+    if (response.status === 404) return null;
+    if (!response.ok) {
+      throw new Error(`Gitea GET ${path} failed with ${response.status}`);
+    }
+    return response.json();
+  }
+
+  async function rawRawRequest(path) {
+    if (!fetchImpl) throw new Error('Gitea service requires a fetch implementation');
+    const response = await fetchImpl(`${root}/api/v1${path}`, {
+      method: 'GET',
+      headers: {
+        Accept: 'text/plain',
+        ...(token ? { Authorization: `token ${token}` } : {}),
+      },
+    });
+    if (response.status === 404) return null;
+    if (!response.ok) {
+      throw new Error(`Gitea GET ${path} failed with ${response.status}`);
+    }
+    return response.text();
+  }
+
+  return {
+    available: true,
+    baseUrl: root,
+
+    /**
+     * List tree entries for a repository path at a given ref.
+     * Uses GET /api/v1/repos/{owner}/{repo}/contents/{path}?ref={ref}
+     *
+     * @param {string} org
+     * @param {string} repo
+     * @param {string} ref  — branch name, tag, or commit SHA
+     * @param {string} [path='']
+     * @returns {Promise<Array<{path:string,type:'blob'|'tree',size:number}>|null>}
+     */
+    async listTree(org, repo, ref, path = '') {
+      const encodedPath = path ? encodeURIComponent(path).replace(/%2F/g, '/') : '';
+      const apiPath = `/repos/${encodeURIComponent(org)}/${encodeURIComponent(repo)}/contents/${encodedPath}?ref=${encodeURIComponent(ref)}`;
+      const data = await rawRequest(apiPath);
+      if (data === null) return null;
+
+      // Gitea returns an array for directories, an object for files
+      const entries = Array.isArray(data) ? data : [data];
+      return entries.map((entry) => ({
+        path: entry.path || entry.name,
+        type: entry.type === 'dir' ? 'tree' : 'blob',
+        size: entry.size || 0,
+        sha: entry.sha,
+        name: entry.name,
+      }));
+    },
+
+    /**
+     * Get the raw text content of a file.
+     * Uses GET /api/v1/repos/{owner}/{repo}/raw/{filepath}?ref={ref}
+     *
+     * @param {string} org
+     * @param {string} repo
+     * @param {string} ref
+     * @param {string} path
+     * @returns {Promise<string|null>}
+     */
+    async getBlob(org, repo, ref, path) {
+      const encodedPath = path ? encodeURIComponent(path).replace(/%2F/g, '/') : '';
+      const apiPath = `/repos/${encodeURIComponent(org)}/${encodeURIComponent(repo)}/raw/${encodedPath}?ref=${encodeURIComponent(ref)}`;
+      return rawRawRequest(apiPath);
+    },
+
+    /**
+     * List branches for a repository.
+     * Uses GET /api/v1/repos/{owner}/{repo}/branches
+     *
+     * @param {string} org
+     * @param {string} repo
+     * @returns {Promise<Array<{name:string,sha:string,protected:boolean}>|null>}
+     */
+    async listBranches(org, repo) {
+      const data = await rawRequest(`/repos/${encodeURIComponent(org)}/${encodeURIComponent(repo)}/branches`);
+      if (data === null) return null;
+      return data.map((b) => ({
+        name: b.name,
+        sha: b.commit?.id || b.commit?.sha || '',
+        protected: b.protected || false,
+      }));
+    },
+
+    /**
+     * Get file metadata + base64-decoded content for a path.
+     * Uses GET /api/v1/repos/{owner}/{repo}/contents/{path}?ref={ref}
+     *
+     * @param {string} org
+     * @param {string} repo
+     * @param {string} ref
+     * @param {string} path
+     * @returns {Promise<{path:string,content:string,size:number,sha:string,encoding:string}|null>}
+     */
+    async getFileContent(org, repo, ref, path) {
+      const encodedPath = path ? encodeURIComponent(path).replace(/%2F/g, '/') : '';
+      const apiPath = `/repos/${encodeURIComponent(org)}/${encodeURIComponent(repo)}/contents/${encodedPath}?ref=${encodeURIComponent(ref)}`;
+      const data = await rawRequest(apiPath);
+      if (data === null || Array.isArray(data)) return null; // null = not found, array = directory
+
+      // Gitea returns content as base64 — decode it
+      const rawContent = data.content
+        ? Buffer.from(data.content.replace(/\n/g, ''), 'base64').toString('utf8')
+        : '';
+
+      return {
+        path: data.path || path,
+        content: rawContent,
+        size: data.size || Buffer.byteLength(rawContent, 'utf8'),
+        sha: data.sha,
+        encoding: 'utf-8',
+        lastCommit: data.last_commit_sha || null,
+      };
+    },
+
+    /**
+     * Create a repository inside an org.
+     * Delegates to the underlying gitea-backend.
+     *
+     * @param {string} org
+     * @param {string} name
+     * @param {{ private?: boolean, defaultBranch?: string, description?: string }} [repoOptions]
+     */
+    async createRepository(org, name, repoOptions = {}) {
+      return backend.createRepository({
+        owner: org,
+        name,
+        private: repoOptions.private ?? true,
+        defaultBranch: repoOptions.defaultBranch || 'main',
+        description: repoOptions.description || '',
+      });
+    },
+  };
+}

package/src/handoff.js

@@ -0,0 +1,98 @@
+export const HANDOFF_COMMANDS = Object.freeze({
+  build: 'npm run build',
+  demo: 'npm run demo',
+  serve: 'npm run serve',
+  check: 'npm run check',
+  test: 'npm test',
+  smoke: 'npm run smoke',
+  validateDocs: 'npm run validate:docs',
+  e2e: 'npm run e2e',
+  packageCheck: 'npm run package:check',
+  setupMinikube: 'npm run setup:minikube -- --dry-run',
+  dev: 'npm run dev',
+  uiBuild: 'npm run ui:build',
+  uiValidate: 'npm run ui:validate'
+});
+
+export const HANDOFF_DOCS = Object.freeze([
+  'docs/README.md',
+  'docs/product-requirements.md',
+  'docs/system-requirements.md',
+  'docs/architecture-spec.md',
+  'docs/user-stories.md',
+  'docs/roadmap-mvp.md',
+  'docs/local-minikube.md',
+  'docs/install.md',
+  'docs/ontology/README.md'
+]);
+
+export function createKradleHandoffSummary(demo, { packageInfo = {}, generatedAt = new Date().toISOString() } = {}) {
+  const smoke = demo.smoke || { ok: true, assertions: [] };
+  return {
+    project: 'Kradle',
+    description: 'Kubernetes-native forge runtime with Argo CD and Kradle-managed repository hosting',
+    package: {
+      name: packageInfo.name || 'kradle',
+      version: packageInfo.version || '0.1.0',
+      private: packageInfo.private !== false
+    },
+    entrypoints: {
+      library: './src/index.js',
+      cli: './bin/kradle-demo.mjs',
+      runtimeServer: './bin/kradle-server.mjs',
+      webPreview: './public/index.html',
+      nextUi: './apps/web',
+      generatedSummary: './dist/kradle-summary.json',
+      lifecycleSnapshot: './dist/kradle-lifecycle.json',
+      helmChart: './charts/kradle',
+      minikubeSetup: './scripts/setup-minikube.mjs'
+    },
+    commands: { ...HANDOFF_COMMANDS },
+    docs: [...HANDOFF_DOCS],
+    components: demo.components || [],
+    lifecycle: demo.lifecycle || null,
+    resources: Object.fromEntries(Object.entries(demo.resources).map(([key, value]) => [key, value?.kind || 'workflow'])),
+    storage: demo.controlPlane.storageReport(),
+    excellentFlows: demo.ui.dashboard.excellentFlows,
+    agents: demo.agents ? {
+      stacks: demo.agents.stacks?.count || 0,
+      runs: demo.agents.runs?.count || 0,
+      activeRuns: demo.agents.runs?.active?.length || 0,
+      rules: demo.agents.rules?.count || 0,
+      sessions: demo.agents.sessions?.count || 0,
+      workspaces: demo.agents.workspaces?.count || 0,
+      pendingApprovals: demo.agents.approvals?.pending?.length || 0
+    } : null,
+    operations: { chartPackage: demo.operations.chartPackage, localSetup: demo.operations.localSetup },
+    releaseGates: demo.operations.releaseGates,
+    smoke: {
+      ok: smoke.ok,
+      assertions: smoke.assertions.map(([name, passed]) => ({ name, passed }))
+    },
+    generatedAt
+  };
+}
+
+export function formatHandoffSummary(summary) {
+  const lines = [
+    `${summary.project} ${summary.package.version} — ${summary.description}`,
+    '',
+    'Entrypoints:',
+    ...Object.entries(summary.entrypoints).map(([name, target]) => `- ${name}: ${target}`),
+    '',
+    'Commands:',
+    ...Object.entries(summary.commands).map(([name, command]) => `- ${name}: ${command}`),
+    '',
+    'Storage boundary:',
+    `- etcd: ${summary.storage.etcd.join(', ')}`,
+    `- postgres: ${summary.storage.postgres.join(', ')}`,
+    '',
+    'Excellent flows:',
+    ...summary.excellentFlows.map((flow) => `- ${flow}`),
+    '',
+    `Smoke: ${summary.smoke.ok ? 'pass' : 'fail'}`
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+

package/src/health-probes.js

@@ -0,0 +1,134 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { globalEventBus } from './event-bus.js';
+
+const execFileAsync = promisify(execFileCallback);
+const DEFAULT_TIMEOUT_MS = 3000;
+
+function elapsed(startedAt) {
+  return Date.now() - startedAt;
+}
+
+function trimSlash(value) {
+  return String(value || '').replace(/\/+$/, '');
+}
+
+function redactSecretText(value) {
+  return String(value || '')
+    .replace(/([a-z][a-z0-9+.-]*:\/\/)([^:@/\s]+):([^@/\s]+)@/gi, '$1[redacted]:[redacted]@')
+    .replace(/sk-ant-[A-Za-z0-9_-]+/g, '[redacted]')
+    .replace(/sk-[A-Za-z0-9_-]{12,}/g, '[redacted]')
+    .replace(/(token|password|secret|api[_-]?key)=([^&\s]+)/gi, '$1=[redacted]');
+}
+
+function redactedError(error) {
+  return redactSecretText(error?.message || error || 'unknown error');
+}
+
+function redactedUrl(url) {
+  if (!url) return url;
+  try {
+    const parsed = new URL(url);
+    if (parsed.username) parsed.username = '[redacted]';
+    if (parsed.password) parsed.password = '[redacted]';
+    for (const key of [...parsed.searchParams.keys()]) {
+      if (/token|password|secret|api[_-]?key/i.test(key)) parsed.searchParams.set(key, '[redacted]');
+    }
+    return parsed.toString();
+  } catch {
+    return redactSecretText(url);
+  }
+}
+
+function sanitizeStatus(status) {
+  if (!status || typeof status !== 'object') return status;
+  return Object.fromEntries(Object.entries(status).map(([key, value]) => {
+    if (key === 'reason' || key === 'error' || key === 'url') return [key, redactSecretText(value)];
+    return [key, value];
+  }));
+}
+
+async function httpProbe({ name, url, fetchImpl, timeoutMs }) {
+  if (!url) return { name, status: 'not configured', reason: 'missing-url' };
+  const startedAt = Date.now();
+  try {
+    const signal = typeof AbortSignal?.timeout === 'function'
+      ? AbortSignal.timeout(timeoutMs)
+      : undefined;
+    const response = await fetchImpl(url, { signal });
+    return response?.ok
+      ? { name, status: 'ok', latencyMs: elapsed(startedAt), url: redactedUrl(url) }
+      : { name, status: 'error', reason: `http-${response?.status || 'unknown'}`, latencyMs: elapsed(startedAt), url: redactedUrl(url) };
+  } catch (error) {
+    return { name, status: 'error', reason: 'request-failed', latencyMs: elapsed(startedAt), error: redactedError(error), url: redactedUrl(url) };
+  }
+}
+
+async function kubernetesProbe({ env, execFileImpl, timeoutMs }) {
+  const startedAt = Date.now();
+  const command = env.KRADLE_KUBECTL || 'kubectl';
+  try {
+    const result = await execFileImpl(command, ['cluster-info'], { timeout: timeoutMs });
+    const output = [result?.stdout, result?.stderr].filter(Boolean).join('\n').trim();
+    return { status: 'ok', reason: 'cluster-info', latencyMs: elapsed(startedAt), context: output || null };
+  } catch (error) {
+    return { status: 'error', reason: 'cluster-info-failed', latencyMs: elapsed(startedAt), error: redactedError(error) };
+  }
+}
+
+function assistantProbe(env) {
+  const key = env.ANTHROPIC_API_KEY || env.KRADLE_ASSISTANT_API_KEY || '';
+  if (!key) return { status: 'not configured', reason: 'missing-key' };
+  if (/^sk-ant-[A-Za-z0-9_-]{12,}$/.test(key) || /^sk-[A-Za-z0-9_-]{12,}$/.test(key)) {
+    return { status: 'ok', reason: 'valid-format' };
+  }
+  return { status: 'error', reason: 'invalid-format' };
+}
+
+function eventTransportProbe(eventBus) {
+  try {
+    const status = sanitizeStatus(eventBus?.status?.());
+    if (!status) return { status: 'unknown', reason: 'no-event-bus' };
+    return {
+      status: status.status === 'ok' ? 'ok' : status.status || 'unknown',
+      ...status,
+    };
+  } catch (error) {
+    return { status: 'error', reason: 'status-failed', error: redactedError(error) };
+  }
+}
+
+export async function collectKradleHealthProbes(options = {}) {
+  const env = options.env || process.env;
+  const timeoutMs = Number(options.timeoutMs || env.KRADLE_HEALTH_TIMEOUT_MS || env.KRADLE_KUBECTL_TIMEOUT_MS || DEFAULT_TIMEOUT_MS);
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const execFileImpl = options.execFileImpl || execFileAsync;
+  const eventBus = options.eventBus || globalEventBus;
+  const giteaUrl = env.KRADLE_GITEA_HTTP_URL ? `${trimSlash(env.KRADLE_GITEA_HTTP_URL)}/api/v1/version` : '';
+  const agentMuxBase = env.AGENT_MUX_URL || env.AGENT_GATEWAY_URL || '';
+  const agentMuxUrl = agentMuxBase ? `${trimSlash(agentMuxBase)}/healthz` : '';
+  const controllerUrl = env.KRADLE_CONTROLLER_URL ? `${trimSlash(env.KRADLE_CONTROLLER_URL)}/healthz` : '';
+
+  const [kubernetes, gitea, agentMux, controller, assistant, eventTransport] = await Promise.all([
+    kubernetesProbe({ env, execFileImpl, timeoutMs }),
+    httpProbe({ name: 'gitea', url: giteaUrl, fetchImpl, timeoutMs }),
+    httpProbe({ name: 'agentMux', url: agentMuxUrl, fetchImpl, timeoutMs }),
+    httpProbe({ name: 'controller', url: controllerUrl, fetchImpl, timeoutMs }),
+    Promise.resolve(assistantProbe(env)),
+    Promise.resolve(eventTransportProbe(eventBus)),
+  ]);
+
+  return {
+    kubernetes,
+    gitea,
+    agentMux,
+    agentGateway: agentMux,
+    controller,
+    assistant,
+    eventTransport,
+  };
+}
+
+export function healthStatusValue(probe) {
+  return probe?.status || 'unknown';
+}

package/src/hooks-events.js

@@ -0,0 +1,63 @@
+import { createHmac } from 'node:crypto';
+import { createResource } from './resource-model.js';
+
+export class WebhookBus {
+  constructor({ controlPlane, secret = 'kradle-dev-secret' }) { this.controlPlane = controlPlane; this.secret = secret; }
+
+  subscribe({ name, namespace = 'kradle-org-default', organizationRef = 'default', url, events = ['pullrequest.created'], mode = 'active' }, user) {
+    return this.controlPlane.create(createResource('WebhookSubscription', { name, namespace }, {
+      organizationRef, url, events, signing: { algorithm: 'hmac-sha256', secretRef: `${name}-secret` }, mode
+    }, { ready: true }), user);
+  }
+
+  sign(payload) { return createHmac('sha256', this.secret).update(JSON.stringify(payload)).digest('hex'); }
+
+  deliver({ subscriptionName, namespace = 'kradle-org-default', organizationRef = 'default', eventType, payload, response = { status: 202, body: 'accepted' } }, user) {
+    const subscription = this.controlPlane.get('WebhookSubscription', namespace, subscriptionName);
+    if (!subscription) throw new Error(`WebhookSubscription ${subscriptionName} not found`);
+    if (!subscription.spec.events.includes(eventType)) throw new Error(`${subscriptionName} does not subscribe to ${eventType}`);
+    const delivery = createResource('WebhookDelivery', {
+      name: `${subscriptionName}-${Date.now()}-${this.controlPlane.list('WebhookDelivery', { namespace }).items.length + 1}`,
+      namespace,
+      labels: { subscription: subscriptionName, eventType }
+    }, {
+      organizationRef: subscription.spec.organizationRef || organizationRef,
+      subscription: subscriptionName,
+      url: subscription.spec.url,
+      eventType,
+      payload,
+      signature: this.sign(payload),
+      replayOf: payload.replayOf || null
+    }, {
+      phase: response.status >= 200 && response.status < 300 ? 'Delivered' : 'Failed',
+      response,
+      attempts: 1
+    });
+    return this.controlPlane.create(delivery, user);
+  }
+
+  replay(delivery, user) {
+    return this.deliver({
+      subscriptionName: delivery.spec.subscription,
+      namespace: delivery.metadata.namespace,
+      organizationRef: delivery.spec.organizationRef,
+      eventType: delivery.spec.eventType,
+      payload: { ...delivery.spec.payload, replayOf: delivery.metadata.name },
+      response: { status: 202, body: 'replayed' }
+    }, user);
+  }
+
+  inspect(delivery) {
+    return {
+      name: delivery.metadata.name,
+      subscription: delivery.spec.subscription,
+      eventType: delivery.spec.eventType,
+      phase: delivery.status.phase,
+      attempts: delivery.status.attempts,
+      response: delivery.status.response,
+      signature: delivery.spec.signature,
+      replayOf: delivery.spec.replayOf,
+      replayable: Boolean(delivery.spec.subscription && delivery.spec.eventType)
+    };
+  }
+}

package/src/hooks-lifecycle.js

@@ -0,0 +1,117 @@
+export const HOOKS_LIFECYCLE_BOUNDARY = {
+  role: 'hooks-lifecycle',
+  scope: 'Lifecycle event emission at key dispatch flow transitions',
+  owns: ['lifecycle event emission'],
+  delegatesTo: ['event-bus'],
+  mustNotOwn: ['event storage', 'dispatch logic', 'session management']
+};
+
+/**
+ * Create a hooks lifecycle emitter that broadcasts structured events to an event bus.
+ * @param {{ emit: Function }} eventBus
+ * @returns {object}
+ */
+export function createHooksLifecycleEmitter(eventBus) {
+  if (!eventBus || typeof eventBus.emit !== 'function') {
+    throw new Error('createHooksLifecycleEmitter requires an eventBus with an emit method');
+  }
+
+  return {
+    emitRunCreated(run) {
+      eventBus.emit({
+        type: 'hook',
+        event: 'RUN_CREATED',
+        runId: run.metadata?.name,
+        stack: run.spec?.agentStack,
+        timestamp: new Date().toISOString(),
+      });
+    },
+
+    emitRunCompleted(run, result) {
+      const startedAt = run.status?.queuedAt ? new Date(run.status.queuedAt) : null;
+      const now = new Date();
+      const duration = startedAt ? now - startedAt : null;
+      eventBus.emit({
+        type: 'hook',
+        event: 'RUN_COMPLETED',
+        runId: run.metadata?.name,
+        result: result?.phase || 'Completed',
+        duration,
+        timestamp: now.toISOString(),
+      });
+    },
+
+    emitStepStarted(run, step) {
+      eventBus.emit({
+        type: 'hook',
+        event: 'STEP_STARTED',
+        runId: run.metadata?.name,
+        step,
+        timestamp: new Date().toISOString(),
+      });
+    },
+
+    emitStepEnded(run, step, result) {
+      eventBus.emit({
+        type: 'hook',
+        event: 'STEP_ENDED',
+        runId: run.metadata?.name,
+        step,
+        result,
+        timestamp: new Date().toISOString(),
+      });
+    },
+
+    emitApprovalRequested(approval) {
+      eventBus.emit({
+        type: 'hook',
+        event: 'APPROVAL_REQUESTED',
+        approvalId: approval.metadata?.name,
+        action: approval.spec?.action,
+        requestedBy: approval.spec?.requestedBy,
+        timestamp: new Date().toISOString(),
+      });
+    },
+
+    emitApprovalDecided(approval) {
+      eventBus.emit({
+        type: 'hook',
+        event: 'APPROVAL_DECIDED',
+        approvalId: approval.metadata?.name,
+        action: approval.spec?.action,
+        decision: approval.status?.decision,
+        timestamp: new Date().toISOString(),
+      });
+    },
+
+    emitWorkspaceProvisioned(workspace) {
+      eventBus.emit({
+        type: 'hook',
+        event: 'WORKSPACE_PROVISIONED',
+        workspaceId: workspace.metadata?.name,
+        repository: workspace.spec?.repository,
+        timestamp: new Date().toISOString(),
+      });
+    },
+
+    emitSessionStarted(session) {
+      eventBus.emit({
+        type: 'hook',
+        event: 'SESSION_STARTED',
+        sessionId: session.sessionId || session.metadata?.name,
+        runId: session.runId,
+        timestamp: new Date().toISOString(),
+      });
+    },
+
+    emitSessionEnded(session) {
+      eventBus.emit({
+        type: 'hook',
+        event: 'SESSION_ENDED',
+        sessionId: session.sessionId || session.metadata?.name,
+        runId: session.runId,
+        timestamp: new Date().toISOString(),
+      });
+    },
+  };
+}