@gaia-ai/addon-gaia-ui-artifacts 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @gaia-ai/addon-gaia-ui-artifacts
+
+GAIA TUI: an Artifacts tab on ticket detail, reading assets-ai/<GAIA-nnn>/.
+
+Part of the GAIA CLI. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all addons. Source: https://git.key-tec.de/keytec/gaia (gaia-cli/).

package/dist/src/panel.d.ts

@@ -0,0 +1,6 @@
+import type { UiPanel } from '@gaia-ai/addon-gaia-ui/ui';
+/**
+ * The ticket's generated artifacts — the tree GAIA-371 D3 defines, which D1 left
+ * with no reader at all: transient, gitignored, and listed nowhere else.
+ */
+export declare const artifactsPanel: UiPanel;

package/dist/src/panel.js

@@ -0,0 +1,53 @@
+import { artifactRoots, artifactSections } from './tree.js';
+/** How many lines of one artifact an expanded entry shows (spec D9). */
+const HEAD_LINES = 200;
+const attribute = (doc, name) => {
+    const value = doc?.data?.attributes?.[name];
+    return typeof value === 'string' ? value : '';
+};
+/**
+ * The ticket's generated artifacts — the tree GAIA-371 D3 defines, which D1 left
+ * with no reader at all: transient, gitignored, and listed nowhere else.
+ */
+export const artifactsPanel = {
+    type: 'panel',
+    id: 'gaia/artifacts',
+    title: 'Artifacts',
+    // Present on every open ticket: an absent tree is an EMPTY STATE, not a
+    // hidden tab. Whether artifacts exist is exactly what the operator opens this
+    // to find out — a tab that vanished when there were none would answer the
+    // question by disappearing.
+    match: (ctx) => ctx.routeId === 'ticket.detail',
+    sections: (doc, ctx) => {
+        const identifier = attribute(doc, 'identifier');
+        if (ctx.cwd === undefined || identifier === '') {
+            return [
+                {
+                    heading: 'Artifacts',
+                    lines: [
+                        'This cockpit has no checkout to read artifacts from.',
+                        'Artifacts are transient and local (GAIA-371 D1/D10).',
+                    ],
+                },
+            ];
+        }
+        const roots = artifactRoots(ctx.cwd, identifier, attribute(doc, 'branch_name'));
+        const sections = artifactSections(roots, { headLines: HEAD_LINES });
+        // The empty state NAMES BOTH PROBED PATHS. GAIA-371 D10 is a real hole —
+        // on another machine the worktree is gone — and naming the paths is what
+        // turns a blank tab into a diagnosis.
+        return sections.length > 0
+            ? sections
+            : [
+                {
+                    heading: 'Artifacts',
+                    lines: [
+                        'No artifacts in this checkout. Probed:',
+                        ...roots.map((root) => `  ${root}`),
+                        '',
+                        'Artifacts die with the worktree (GAIA-371 D1/D10).',
+                    ],
+                },
+            ];
+    },
+};

package/dist/src/preset.d.ts

@@ -0,0 +1,2 @@
+import type { GaiaPreset } from '@gaia-ai/core';
+export declare const uiEntries: GaiaPreset['uiEntries'];

package/dist/src/preset.js

@@ -0,0 +1,4 @@
+export const uiEntries = (acc) => [
+    ...acc,
+    '@gaia-ai/addon-gaia-ui-artifacts/ui',
+];

package/dist/src/tree.d.ts

@@ -0,0 +1,30 @@
+import type { PanelSection } from '@gaia-ai/addon-gaia-ui/ui';
+/**
+ * The roots to probe, in order (spec D9).
+ *
+ * Pure path joins: `cwd` comes from `TuiOptions`, `identifier` and `branch` off
+ * the open document, so there is no `git` call and nothing async. The second
+ * root is not a nicety — an operator starts `gaia ui` in the main checkout while
+ * a run writes its artifacts inside the worktree, so probing only the first
+ * would show nothing, systematically.
+ */
+export declare function artifactRoots(cwd: string, identifier: string, branch: string): string[];
+/**
+ * One section per ARTIFACT, headed by its path under the ticket's tree so the
+ * producing tool leads every heading (`vitest/store-green.txt`,
+ * `playwright/logs/walk.txt`) and one tool's artifacts stand together.
+ *
+ * Why per artifact and not per tool directory: the panel contract is
+ * `PanelSection[]` with one collapsible entry per section (spec D4), and D9 asks
+ * for each FILE to be the expandable entry — its collapsed row the producing
+ * command, its expanded body the head of the capture. A section per tool could
+ * carry only one of those two, so the grouping lives in the heading instead,
+ * where it costs the narrow contract nothing.
+ *
+ * The first row of every text artifact is its own first line, which by GAIA-371
+ * D3 is the command that produced it — so the collapsed panel reads as the list
+ * of commands this ticket ran.
+ */
+export declare function artifactSections(roots: readonly string[], { headLines }: {
+    headLines: number;
+}): readonly PanelSection[];

package/dist/src/tree.js

@@ -0,0 +1,141 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The roots to probe, in order (spec D9).
+ *
+ * Pure path joins: `cwd` comes from `TuiOptions`, `identifier` and `branch` off
+ * the open document, so there is no `git` call and nothing async. The second
+ * root is not a nicety — an operator starts `gaia ui` in the main checkout while
+ * a run writes its artifacts inside the worktree, so probing only the first
+ * would show nothing, systematically.
+ */
+export function artifactRoots(cwd, identifier, branch) {
+    const own = join(cwd, 'assets-ai', identifier);
+    return branch.trim() === ''
+        ? [own]
+        : [own, join(cwd, '.gaia-worktrees', branch, 'assets-ai', identifier)];
+}
+/**
+ * Text file heads, memoised per `(path, mtime, size)` — spec D9.
+ *
+ * That key is what makes the cache CORRECT rather than merely fast: keying on
+ * the directory's own mtime would go stale the moment a re-run overwrites a log
+ * in place, because rewriting a file does not touch its directory. There is no
+ * reliance on the `R` key either — it reloads the document and knows nothing
+ * about this tree.
+ */
+const heads = new Map();
+const head = (path, lines) => {
+    const stat = statSync(path);
+    const key = `${path}:${stat.mtimeMs}:${stat.size}`;
+    const hit = heads.get(key);
+    if (hit)
+        return hit;
+    const all = readFileSync(path, 'utf8').replace(/\n$/, '').split('\n');
+    const kept = all.slice(0, lines);
+    if (all.length > lines)
+        kept.push(`… ${all.length - lines} more lines`);
+    heads.set(key, kept);
+    return kept;
+};
+/** Extensions never read: their bytes say nothing a terminal can show. */
+const BINARY = /\.(png|jpe?g|gif|webp|zip|pdf|webm|mp4)$/i;
+/**
+ * One directory's entries, or none when it cannot be read.
+ *
+ * A directory that vanished between the walk and the read is not an error worth
+ * a stack trace — this runs on the DRAW path, and a run writing into the tree is
+ * exactly the situation the panel exists for.
+ */
+const entriesOf = (dir) => {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * One FILE's section — and the same reasoning `entriesOf` states, applied to the
+ * calls that actually touch bytes.
+ *
+ * The race that comment names is not hypothetical for a file: a run unlinks or
+ * rewrites a capture between `readdirSync` and this read and the `stat`/`open`
+ * comes back ENOENT; a log written by a container as root comes back EACCES. On
+ * the DRAW path either one used to escape as a stack trace, and the host's guard
+ * would then have degraded the WHOLE listing to a single failure row — so one
+ * unreadable file would hide every artifact beside it. It costs its own row
+ * instead: the file stays listed under its real heading, the row says plainly
+ * that it could not be read, and it is NOT expandable, because there is nothing
+ * behind the caret to show. The errno leads, since `ENOENT`/`EACCES` is the part
+ * that tells the operator whether to re-run or to fix permissions.
+ */
+const fileSection = (heading, path, headLines) => {
+    try {
+        return BINARY.test(heading)
+            ? // Listed, never read — and NOT expandable, because there is nothing
+                // behind the caret a terminal could show.
+                { heading, lines: [`${statSync(path).size} bytes`] }
+            : { heading, expandable: true, lines: [...head(path, headLines)] };
+    }
+    catch (caught) {
+        const code = caught?.code;
+        return {
+            heading,
+            lines: [
+                `could not be read: ${typeof code === 'string'
+                    ? code
+                    : caught instanceof Error
+                        ? caught.message
+                        : String(caught)}`,
+            ],
+        };
+    }
+};
+/**
+ * One section per ARTIFACT, headed by its path under the ticket's tree so the
+ * producing tool leads every heading (`vitest/store-green.txt`,
+ * `playwright/logs/walk.txt`) and one tool's artifacts stand together.
+ *
+ * Why per artifact and not per tool directory: the panel contract is
+ * `PanelSection[]` with one collapsible entry per section (spec D4), and D9 asks
+ * for each FILE to be the expandable entry — its collapsed row the producing
+ * command, its expanded body the head of the capture. A section per tool could
+ * carry only one of those two, so the grouping lives in the heading instead,
+ * where it costs the narrow contract nothing.
+ *
+ * The first row of every text artifact is its own first line, which by GAIA-371
+ * D3 is the command that produced it — so the collapsed panel reads as the list
+ * of commands this ticket ran.
+ */
+export function artifactSections(roots, { headLines }) {
+    const root = roots.find((candidate) => {
+        try {
+            return statSync(candidate).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+    if (root === undefined)
+        return [];
+    const sections = [];
+    const walk = (dir, prefix) => {
+        // Sorted by name, so the listing is the same on every draw and on every
+        // filesystem — `readdirSync` promises no order of its own.
+        const sorted = [...entriesOf(dir)].sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of sorted) {
+            const path = join(dir, entry.name);
+            const heading = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+            if (entry.isDirectory()) {
+                walk(path, heading);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            sections.push(fileSection(heading, path, headLines));
+        }
+    };
+    walk(root, '');
+    return sections;
+}

package/dist/src/ui.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/ui.js

@@ -0,0 +1,6 @@
+// The entry module: it registers at IMPORT time, which is Storybook-faithful for
+// the addon author and is why the kernel drains the collector once rather than
+// handing a store around (spec D3).
+import { register } from '@gaia-ai/addon-gaia-ui/ui';
+import { artifactsPanel } from './panel.js';
+register('gaia/artifacts', (api) => api.add(artifactsPanel.id, artifactsPanel));

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@gaia-ai/addon-gaia-ui-artifacts",
+  "version": "0.10.0",
+  "description": "GAIA TUI: an Artifacts tab on ticket detail, reading assets-ai/<GAIA-nnn>/.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/panel.js",
+    "./preset": "./dist/src/preset.js",
+    "./ui": "./dist/src/ui.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/keytec/gaia.git",
+    "directory": "gaia-cli/addons/gaia-ui-artifacts"
+  },
+  "peerDependencies": {
+    "@gaia-ai/addon-gaia-ui": "^0.10.0",
+    "@gaia-ai/core": "^0.10.0"
+  }
+}