@yanolja-next/noya-sdk 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# Noya
+
+Production issue reports into pre-triaged Jira tickets and ready-to-review PRs.
+
+This repository contains a local Node.js + TypeScript MVP:
+
+- Browser SDK wrapper entry point: `src/sdk.ts`
+- Backend orchestrator and dashboard: `src/server.ts`, `public/`
+- Customer runner: `src/runner.ts`
+- Local issue and draft PR artifacts by default
+- Optional GitHub/Jira issue providers when explicitly configured with token
+  environment variables
+- GitHub/Jira issues receive a fix-result comment after local draft PR creation
+- Project integration config rejects inline credentials; use `*_env` settings
+  for token/secret references
+- Optional telemetry event lookup when a project has provider integration settings
+- Optional provider webhook HMAC verification via
+  `integrations.telemetry.webhook_secret_env`
+- SDK session recording wiring with optional Replay/Feedback integration
+  registration
+- Optional runner Bearer authentication via project `runner.token_env`
+- Approved fix command refs for local Claude Code/agent execution, with
+  shell-free process spawning, isolated repo checkout, and local draft PR
+  artifacts
+- Checkout status and patch artifacts are attached to local draft PR output when
+  an approved agent changes files
+- Artifact serving is constrained to each project's `artifact_dir`
+- Optional dashboard/admin artifact protection via `NOYA_ADMIN_TOKEN`
+- Project-level artifact retention cleanup via
+  `POST /api/projects/:project_key/retention/cleanup`
+- Idempotent manual fix approval so repeated clicks do not create duplicate jobs
+- Audit entries for individual collector policy decisions and fix agent command
+  execution
+- SDK network correlation for `x-request-id`, `x-trace-id`, and `traceparent`
+- SDK/provider screenshot URLs are preserved as issue evidence
+- Telemetry breadcrumbs are surfaced in compiled issue bodies
+- Runner lease timeout/requeue and collector `max_entries` / `max_bytes` limits
+- Server-side validation for collect/fix runner completion payloads
+- No-runner flow creates an immediate issue with unavailable internal context
+  clearly marked
+- Dashboard links for local issue and draft PR artifacts
+- Dashboard readiness checks for artifact storage, runner repo, tokens, and issue
+  providers
+- Dashboard project config editor with server-side validation
+- Project edits preserve immutable `created_at` metadata
+- agency-platform customer sample: `examples/agency-platform/`
+
+The local implementation intentionally does not deploy, push, merge, or write to
+production systems. The PR flow creates a local draft PR artifact for review.
+External issue providers are opt-in and are covered by mock-server tests.
+
+- [PRD](docs/PRD.md)
+- [AI agent integration guide](docs/AGENT_INTEGRATION.md)
+- [GCP deployment guide](docs/DEPLOY_GCP.md)
+
+## Run Locally
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+Open `http://localhost:3456`.
+
+To simulate the customer runner once:
+
+```bash
+npm run runner -- examples/agency-platform/noya.runner.json
+```
+
+If the project is configured with `runner.token_env`, export the same token
+before running the runner:
+
+```bash
+export NOYA_AGENCY_PLATFORM_RUNNER_TOKEN=local-runner-token
+```
+
+To protect dashboard, local artifact, project config, retention cleanup, and fix
+approval endpoints in a shared local environment:
+
+```bash
+export NOYA_ADMIN_TOKEN=local-admin-token
+```
+
+The dashboard sends this token from `localStorage.noya_admin_token` when set.
+
+## Verify
+
+```bash
+npm test
+npm run test:e2e
+```
+
+`npm run test:e2e` starts the orchestrator, submits an agency-platform sample
+report, runs collect mode, approves a local fix from the dashboard in headless
+Chrome, runs fix mode, and verifies that a local draft PR artifact was created.
+It also verifies telemetry webhook intake, collector policy denial for raw command
+collectors, telemetry event lookup, GitHub/Jira providers against local mock
+servers, approved fix command execution, runner heartbeat/fail lifecycle, and
+runner Bearer authentication. `npm test` also verifies provider webhook signature
+checks, stale runner lease requeue, collector output limits, duplicate issue
+linking, idempotent fix approval, collector/agent audit entries,
+browser-visible artifact links, readiness checks, SDK request correlation,
+project config validation, context redaction, and recording tag/context wiring.
+It also checks artifact retention cleanup and artifact path boundary enforcement.
+Optional admin-token protection is covered by API tests.

package/dist/src/adapters.d.ts

@@ -0,0 +1,25 @@
+import type { Job, JsonObject, Project, Issue } from "./types.js";
+import type { JsonStore } from "./store.js";
+export declare function createProviderIssue({ store, project, issue, }: {
+    store: JsonStore;
+    project: Project;
+    issue: Issue;
+}): Promise<JsonObject>;
+export declare function updateProviderIssueAfterFix({ store, project, issue, draftPr, result, }: {
+    store: JsonStore;
+    project: Project;
+    issue: Issue;
+    draftPr: JsonObject;
+    result: JsonObject;
+}): Promise<JsonObject | null>;
+export declare function createLocalDraftPr({ store, project, job, result, }: {
+    store: JsonStore;
+    project: Project;
+    job: Job;
+    result: {
+        branch?: string;
+        changed_files?: string[];
+        tests?: string[];
+        transcript?: string;
+    };
+}): JsonObject;

package/dist/src/adapters.js

@@ -0,0 +1,244 @@
+import fs from "node:fs";
+import path from "node:path";
+export async function createProviderIssue({ store, project, issue, }) {
+    if (project.issue_provider === "github") {
+        return createGitHubIssue({ store, project, issue });
+    }
+    if (project.issue_provider === "jira") {
+        return createJiraIssue({ store, project, issue });
+    }
+    return createLocalIssue({ store, project, issue });
+}
+export async function updateProviderIssueAfterFix({ store, project, issue, draftPr, result, }) {
+    if (project.issue_provider === "github") {
+        return createGitHubFixComment({ store, project, issue, draftPr, result });
+    }
+    if (project.issue_provider === "jira") {
+        return createJiraFixComment({ store, project, issue, draftPr, result });
+    }
+    return null;
+}
+function createLocalIssue({ store, project, issue, }) {
+    const dir = path.join(project.artifact_dir ?? ".noya/artifacts", "issues");
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${issue.id}.md`);
+    fs.writeFileSync(filePath, `# ${issue.title}\n\n${issue.body}\n`);
+    store.audit("issue.created.local", {
+        project_key: project.project_key,
+        issue_id: issue.id,
+        path: filePath,
+    });
+    return {
+        provider: project.issue_provider ?? "local",
+        external_id: issue.id,
+        url: `file://${filePath}`,
+        web_url: `/artifacts/issues/${issue.id}`,
+        path: filePath,
+    };
+}
+async function createGitHubIssue({ store, project, issue, }) {
+    const github = (project.integrations?.github ?? {});
+    const apiBase = String(github.api_base ?? "https://api.github.com");
+    const owner = requiredString(github.owner, "github.owner");
+    const repo = requiredString(github.repo, "github.repo");
+    const token = tokenFromEnv(requiredString(github.token_env, "github.token_env"));
+    const response = await fetch(`${apiBase}/repos/${owner}/${repo}/issues`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${token}`,
+            accept: "application/vnd.github+json",
+            "content-type": "application/json",
+            "user-agent": "noya-local",
+        },
+        body: JSON.stringify({ title: issue.title, body: issue.body }),
+    });
+    if (!response.ok)
+        throw new Error(`GitHub issue creation failed: ${response.status}`);
+    const payload = (await response.json());
+    store.audit("issue.created.github", {
+        project_key: project.project_key,
+        issue_id: issue.id,
+        external_id: String(payload.number ?? payload.id ?? ""),
+    });
+    return {
+        provider: "github",
+        external_id: String(payload.number ?? payload.id ?? ""),
+        url: String(payload.html_url ?? payload.url ?? ""),
+    };
+}
+async function createJiraIssue({ store, project, issue, }) {
+    const jira = (project.integrations?.jira ?? {});
+    const apiBase = requiredString(jira.api_base, "jira.api_base").replace(/\/$/, "");
+    const projectKey = requiredString(jira.project_key, "jira.project_key");
+    const issueType = String(jira.issue_type ?? "Bug");
+    const email = requiredString(jira.email, "jira.email");
+    const token = tokenFromEnv(requiredString(jira.token_env, "jira.token_env"));
+    const response = await fetch(`${apiBase}/rest/api/3/issue`, {
+        method: "POST",
+        headers: {
+            authorization: `Basic ${Buffer.from(`${email}:${token}`).toString("base64")}`,
+            accept: "application/json",
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({
+            fields: {
+                project: { key: projectKey },
+                issuetype: { name: issueType },
+                summary: issue.title,
+                description: jiraDoc(issue.body),
+            },
+        }),
+    });
+    if (!response.ok)
+        throw new Error(`Jira issue creation failed: ${response.status}`);
+    const payload = (await response.json());
+    store.audit("issue.created.jira", {
+        project_key: project.project_key,
+        issue_id: issue.id,
+        external_id: String(payload.key ?? payload.id ?? ""),
+    });
+    return {
+        provider: "jira",
+        external_id: String(payload.key ?? payload.id ?? ""),
+        url: payload.self ? String(payload.self) : "",
+    };
+}
+async function createGitHubFixComment({ store, project, issue, draftPr, result, }) {
+    const github = (project.integrations?.github ?? {});
+    const apiBase = String(github.api_base ?? "https://api.github.com");
+    const owner = requiredString(github.owner, "github.owner");
+    const repo = requiredString(github.repo, "github.repo");
+    const token = tokenFromEnv(requiredString(github.token_env, "github.token_env"));
+    const issueNumber = requiredString(issue.integration?.external_id, "github issue external_id");
+    const response = await fetch(`${apiBase}/repos/${owner}/${repo}/issues/${issueNumber}/comments`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${token}`,
+            accept: "application/vnd.github+json",
+            "content-type": "application/json",
+            "user-agent": "noya-local",
+        },
+        body: JSON.stringify({ body: fixCommentMarkdown({ draftPr, result }) }),
+    });
+    if (!response.ok)
+        throw new Error(`GitHub issue comment failed: ${response.status}`);
+    const payload = (await response.json());
+    store.audit("fix.provider_update.github", {
+        project_key: project.project_key,
+        issue_id: issue.id,
+        external_id: issueNumber,
+    });
+    return {
+        provider: "github",
+        external_id: String(payload.id ?? ""),
+        url: String(payload.html_url ?? payload.url ?? ""),
+    };
+}
+async function createJiraFixComment({ store, project, issue, draftPr, result, }) {
+    const jira = (project.integrations?.jira ?? {});
+    const apiBase = requiredString(jira.api_base, "jira.api_base").replace(/\/$/, "");
+    const email = requiredString(jira.email, "jira.email");
+    const token = tokenFromEnv(requiredString(jira.token_env, "jira.token_env"));
+    const issueKey = requiredString(issue.integration?.external_id, "jira issue external_id");
+    const response = await fetch(`${apiBase}/rest/api/3/issue/${encodeURIComponent(issueKey)}/comment`, {
+        method: "POST",
+        headers: {
+            authorization: `Basic ${Buffer.from(`${email}:${token}`).toString("base64")}`,
+            accept: "application/json",
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({ body: jiraDoc(fixCommentMarkdown({ draftPr, result })) }),
+    });
+    if (!response.ok)
+        throw new Error(`Jira issue comment failed: ${response.status}`);
+    const payload = (await response.json());
+    store.audit("fix.provider_update.jira", {
+        project_key: project.project_key,
+        issue_id: issue.id,
+        external_id: issueKey,
+    });
+    return {
+        provider: "jira",
+        external_id: String(payload.id ?? ""),
+        url: String(payload.self ?? ""),
+    };
+}
+function fixCommentMarkdown({ draftPr, result }) {
+    return [
+        "## Noya Fix Result",
+        "",
+        `Local draft PR: ${String(draftPr.web_url ?? draftPr.url ?? "unavailable")}`,
+        `Branch: ${String(result.branch ?? "unavailable")}`,
+        "",
+        "### Changed Files",
+        bulletList(result.changed_files),
+        "",
+        "### Verification",
+        bulletList(result.tests),
+        "",
+        "Push, merge, deploy, and production writes were not performed by Noya.",
+    ].join("\n");
+}
+function bulletList(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return "- Unavailable.";
+    return value.map((entry) => `- ${String(entry)}`).join("\n");
+}
+function requiredString(value, name) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Missing ${name} integration setting`);
+    }
+    return value;
+}
+function tokenFromEnv(name) {
+    const value = process.env[name];
+    if (!value)
+        throw new Error(`Missing integration token env var: ${name}`);
+    return value;
+}
+function jiraDoc(markdown) {
+    return {
+        type: "doc",
+        version: 1,
+        content: [
+            {
+                type: "paragraph",
+                content: [{ type: "text", text: markdown.slice(0, 32000) }],
+            },
+        ],
+    };
+}
+export function createLocalDraftPr({ store, project, job, result, }) {
+    const dir = path.join(project.artifact_dir ?? ".noya/artifacts", "prs");
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${job.id}.md`);
+    const body = [
+        `# Local Draft PR: ${job.issue_id}`,
+        "",
+        `Project: ${project.name}`,
+        `Job: ${job.id}`,
+        `Branch: ${result.branch ?? "noya/local-draft"}`,
+        "",
+        "## Changed Files",
+        ...(result.changed_files ?? ["No file edits were made by the dry-run agent."]).map((file) => `- ${file}`),
+        "",
+        "## Verification",
+        ...(result.tests ?? ["No tests configured."]).map((test) => `- ${test}`),
+        "",
+        "## Transcript",
+        result.transcript ?? "No transcript.",
+    ].join("\n");
+    fs.writeFileSync(filePath, `${body}\n`);
+    store.audit("fix.local_draft_pr.created", {
+        project_key: project.project_key,
+        job_id: job.id,
+        path: filePath,
+    });
+    return {
+        provider: "local_draft_pr",
+        external_id: job.id,
+        url: `file://${filePath}`,
+        web_url: `/artifacts/prs/${job.id}`,
+        path: filePath,
+    };
+}

package/dist/src/issueCompiler.d.ts

@@ -0,0 +1,17 @@
+import type { JsonValue, Project, Report } from "./types.js";
+type CollectorResult = {
+    context?: {
+        logs?: JsonValue;
+        domain_snapshot?: JsonValue;
+    };
+    policy?: JsonValue;
+};
+export declare function compileIssue({ report, project, collectorResult, }: {
+    report: Report;
+    project: Project;
+    collectorResult?: CollectorResult | null;
+}): {
+    title: string;
+    body: string;
+};
+export {};

package/dist/src/issueCompiler.js

@@ -0,0 +1,81 @@
+function bulletList(values) {
+    if (!values || values.length === 0)
+        return "- Unavailable.";
+    return values.map((value) => `- ${value}`).join("\n");
+}
+function objectBlock(value) {
+    if (!value || typeof value !== "object" || Object.keys(value).length === 0)
+        return "Unavailable.";
+    return `\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
+}
+function optionalStrings(values) {
+    return values.filter((value) => typeof value === "string" && value.length > 0);
+}
+function feedbackMessage(feedback) {
+    if (!feedback || typeof feedback !== "object" || Array.isArray(feedback))
+        return undefined;
+    const value = feedback.message;
+    return typeof value === "string" ? value : undefined;
+}
+export function compileIssue({ report, project, collectorResult, }) {
+    const context = collectorResult?.context ?? {};
+    const telemetry = report.telemetry ?? report.sentry ?? {};
+    const hints = report.hints ?? {};
+    const summary = report.message ||
+        feedbackMessage(report.feedback) ||
+        `${project.name}: production issue report ${report.id}`;
+    const title = `[${project.name}] ${summary}`.slice(0, 140);
+    const body = [
+        `# Summary\n${summary}`,
+        `# Impact\n${report.impact || "User-reported production issue. Impact needs owner confirmation."}`,
+        `# Environment\n${objectBlock({
+            project: project.name,
+            environment: report.environment,
+            release: report.release,
+            route: report.route,
+            browser: report.browser,
+        })}`,
+        `# Evidence\n${bulletList(optionalStrings([
+            telemetry.event_id ? `Telemetry event: ${telemetry.event_id}` : null,
+            telemetry.replay_id ? `Session replay: ${telemetry.replay_id}` : null,
+            telemetry.feedback_id ? `User feedback: ${telemetry.feedback_id}` : null,
+            report.screenshot_url ? `Screenshot: ${report.screenshot_url}` : null,
+            report.request_id ? `Request ID: ${report.request_id}` : null,
+        ]))}`,
+        `# Reproduction Steps\n${bulletList(report.reproduction_steps)}`,
+        `# Expected Behavior\n${report.expected_behavior || "The user can complete the intended workflow without errors."}`,
+        `# Actual Behavior\n${report.actual_behavior || summary}`,
+        `# Confirmed Facts\n${bulletList(optionalStrings([
+            `Report ID ${report.id} was received by Noya.`,
+            report.route ? `The report was captured on route ${report.route}.` : null,
+            Object.keys(hints).length > 0 ? `Correlation hints were extracted: ${Object.keys(hints).join(", ")}.` : null,
+            collectorResult ? "Customer runner returned a redacted context bundle." : null,
+        ]))}`,
+        `# Inferences / Suspected Cause\n${bulletList([
+            report.suspected_area
+                ? `Suspected area from metadata: ${report.suspected_area}.`
+                : "Needs engineering investigation; Noya is not asserting root cause.",
+        ])}`,
+        `# Relevant Logs\n${objectBlock(context.logs)}`,
+        `# Relevant Domain Snapshot\n${objectBlock(context.domain_snapshot)}`,
+        `# Telemetry Breadcrumbs\n${objectBlock(report.context?.sentry_breadcrumbs)}`,
+        `# Collector Policy Decisions\n${objectBlock(collectorResult?.policy)}`,
+        `# Telemetry Links\n${bulletList(optionalStrings([
+            telemetry.event_url ? telemetry.event_url : null,
+            telemetry.replay_url ? telemetry.replay_url : null,
+        ]))}`,
+        `# Agent Investigation Hints\n${objectBlock({
+            hints,
+            frontend_context: report.context ?? {},
+            suspected_files: report.suspected_files ?? [],
+            repo_path: project.runner?.repo_path,
+        })}`,
+        `# Definition of Done\n${bulletList([
+            "Root cause is confirmed or explicitly ruled out.",
+            "Regression test or focused verification is added when practical.",
+            "Fix opens a reviewable PR or local draft PR artifact.",
+            "No merge, deploy, or production write is performed by Noya.",
+        ])}`,
+    ].join("\n\n");
+    return { title, body };
+}

package/dist/src/orchestrator.d.ts

@@ -0,0 +1,59 @@
+import type { Capabilities, Issue, Job, JsonObject, Project, Report } from "./types.js";
+import type { JsonStore } from "./store.js";
+type ProjectInput = Partial<Project> & Pick<Project, "project_key">;
+type ReportEnvelope = JsonObject & {
+    report_id?: string;
+    project_key: string;
+    message?: string;
+    impact?: string;
+    environment?: string;
+    release?: string;
+    route?: string;
+    browser?: string;
+    request_id?: string;
+    screenshot_url?: string;
+    telemetry?: Report["telemetry"];
+    sentry?: Report["sentry"];
+    feedback?: Report["feedback"];
+    context?: Report["context"];
+    reproduction_steps?: string[];
+    expected_behavior?: string;
+    actual_behavior?: string;
+    suspected_area?: string;
+    suspected_files?: string[];
+};
+export declare function receiveSentryWebhook(store: JsonStore, payload: JsonObject): Promise<{
+    report: Report;
+    job: Job;
+    issue: null;
+} | {
+    report: Report;
+    job: null;
+    issue: Issue;
+}>;
+export declare function upsertProject(store: JsonStore, input: ProjectInput): Project;
+export declare function receiveReport(store: JsonStore, envelope: ReportEnvelope): Promise<{
+    report: Report;
+    job: Job;
+    issue: null;
+} | {
+    report: Report;
+    job: null;
+    issue: Issue;
+}>;
+export declare function nextRunnerJob(store: JsonStore, { projectKey, runnerId, capabilities, }: {
+    projectKey: string | null;
+    runnerId: string;
+    capabilities: Capabilities;
+}): Job | null;
+export declare function heartbeatJob(store: JsonStore, jobId: string): Job;
+export declare function completeJob(store: JsonStore, jobId: string, result: JsonObject): Promise<{
+    job: Job;
+    issue: Issue;
+} | {
+    job: Job;
+    issue?: undefined;
+}>;
+export declare function failJob(store: JsonStore, jobId: string, error: JsonObject): Job;
+export declare function approveFix(store: JsonStore, issueId: string): Job;
+export {};