@assethub/cli 0.1.6 → 0.1.7

package/dist/projectSources.d.ts

@@ -0,0 +1,65 @@
+declare const SCHEMA = "assethub.project-sources.v1";
+type SourceStatus = 'complete' | 'partial' | 'failed' | 'listed';
+type Dependency = {
+    command: string;
+    available: boolean;
+};
+type Placement = {
+    sheet: string;
+    cell?: string;
+    mapping: string;
+};
+export type ProjectSourceArtifact = {
+    relativePath: string;
+    sha256: string;
+    byteSize: number;
+    kind: 'text' | 'metadata' | 'image';
+    origin: {
+        sourceRelativePath: string;
+        sourceSha256: string;
+        extraction: 'copy' | 'text' | 'pdf_page' | 'pdf_text' | 'workbook_media' | 'workbook_cells' | 'video_frame' | 'video_metadata';
+        page?: number;
+        requestedTimestampSeconds?: number;
+        workbookMediaPath?: string;
+        placements?: Placement[];
+    };
+};
+export type ProjectSourceFile = {
+    relativePath: string;
+    sha256: string;
+    byteSize: number;
+    format: string;
+    origin: {
+        sourceRoot: string;
+        relativePath: string;
+    };
+    status: SourceStatus;
+    artifactPaths: string[];
+    warnings: string[];
+};
+export type ProjectSourcesSummary = {
+    schemaVersion: typeof SCHEMA;
+    sourceDir: string;
+    outDir: string;
+    status: 'complete' | 'partial';
+    dependencies: Dependency[];
+    sources: ProjectSourceFile[];
+    images: ProjectSourceArtifact[];
+    artifacts: ProjectSourceArtifact[];
+    requestedExcludedDirectories: string[];
+    excludedDirectories: string[];
+    warnings: string[];
+    summaryPath: string;
+    textPath: string;
+    imagesManifestPath: string;
+};
+export type IngestProjectSourcesOptions = {
+    sourceDir: string;
+    outDir: string;
+    excludedDirectories?: string[];
+    onProgress?: (message: string) => void;
+};
+/** Extract local bytes and provenance only. Semantic analysis and upload are separate CLI steps. */
+export declare function ingestProjectSources(options: IngestProjectSourcesOptions): Promise<ProjectSourcesSummary>;
+export {};
+//# sourceMappingURL=projectSources.d.ts.map

package/dist/projectSources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectSources.d.ts","sourceRoot":"","sources":["../src/projectSources.ts"],"names":[],"mappings":"AAkBA,QAAA,MAAM,MAAM,gCAAgC,CAAA;AAwC5C,KAAK,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAChE,KAAK,UAAU,GAAG;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAC,CAAA;AACvD,KAAK,SAAS,GAAG;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAA;AAChE,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAA;IACnC,MAAM,EAAE;QACN,kBAAkB,EAAE,MAAM,CAAA;QAC1B,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EACN,MAAM,GACN,MAAM,GACN,UAAU,GACV,UAAU,GACV,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,GACb,gBAAgB,CAAA;QACpB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,yBAAyB,CAAC,EAAE,MAAM,CAAA;QAClC,iBAAiB,CAAC,EAAE,MAAM,CAAA;QAC1B,UAAU,CAAC,EAAE,SAAS,EAAE,CAAA;KACzB,CAAA;CACF,CAAA;AACD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAC,CAAA;IAClD,MAAM,EAAE,YAAY,CAAA;IACpB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB,CAAA;AACD,MAAM,MAAM,qBAAqB,GAAG;IAClC,aAAa,EAAE,OAAO,MAAM,CAAA;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;IAC9B,YAAY,EAAE,UAAU,EAAE,CAAA;IAC1B,OAAO,EAAE,iBAAiB,EAAE,CAAA;IAC5B,MAAM,EAAE,qBAAqB,EAAE,CAAA;IAC/B,SAAS,EAAE,qBAAqB,EAAE,CAAA;IAClC,4BAA4B,EAAE,MAAM,EAAE,CAAA;IACtC,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,kBAAkB,EAAE,MAAM,CAAA;CAC3B,CAAA;AACD,MAAM,MAAM,2BAA2B,GAAG;IACxC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC9B,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACvC,CAAA;AA6DD,oGAAoG;AACpG,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC,CAgUhC"}

package/dist/projectSources.js

@@ -0,0 +1,369 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { copyFile, mkdir, readFile, readdir, realpath, stat, writeFile, } from 'node:fs/promises';
+import { extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { EXTRACT_WORKBOOK_PYTHON } from './projectSourcesWorkbook.js';
+const execute = promisify(execFile);
+const SCHEMA = 'assethub.project-sources.v1';
+const MARKER = '.assethub-project-ingest.json';
+const IMAGE_EXTENSIONS = new Set([
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.webp',
+    '.gif',
+    '.avif',
+    '.tif',
+    '.tiff',
+    '.bmp',
+    '.svg',
+    '.exr',
+    '.hdr',
+    '.heic',
+    '.ico',
+]);
+const TEXT_EXTENSIONS = new Set([
+    '.txt',
+    '.md',
+    '.csv',
+    '.tsv',
+    '.json',
+    '.jsonl',
+    '.yaml',
+    '.yml',
+    '.xml',
+    '.srt',
+    '.vtt',
+]);
+const VIDEO_EXTENSIONS = new Set([
+    '.mov',
+    '.mp4',
+    '.m4v',
+    '.webm',
+    '.avi',
+    '.mkv',
+]);
+async function hashFile(path) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+function portable(path) {
+    return path.split(sep).join('/');
+}
+async function command(command, args) {
+    const result = await execute(command, args, {
+        encoding: 'utf8',
+        maxBuffer: 8 * 1024 * 1024,
+        timeout: 300_000,
+    });
+    return result.stdout;
+}
+async function detectDependencies() {
+    return Promise.all([
+        ['python3', '--version'],
+        ['pdftotext', '-v'],
+        ['pdftoppm', '-v'],
+        ['ffmpeg', '-version'],
+        ['ffprobe', '-version'],
+    ].map(async ([name, flag]) => {
+        try {
+            await command(name, [flag]);
+            return { command: name, available: true };
+        }
+        catch {
+            return { command: name, available: false };
+        }
+    }));
+}
+async function isIngestDirectory(path) {
+    try {
+        const marker = JSON.parse(await readFile(join(path, MARKER), 'utf8'));
+        return (typeof marker === 'object' &&
+            marker !== null &&
+            'schemaVersion' in marker &&
+            marker.schemaVersion === SCHEMA);
+    }
+    catch {
+        return false;
+    }
+}
+/** Extract local bytes and provenance only. Semantic analysis and upload are separate CLI steps. */
+export async function ingestProjectSources(options) {
+    const sourceDir = await realpath(resolve(options.sourceDir));
+    if (!(await stat(sourceDir)).isDirectory())
+        throw new Error('Source must be a directory');
+    const excludedPaths = new Set();
+    for (const directory of options.excludedDirectories ?? []) {
+        const path = resolve(sourceDir, directory);
+        const confined = (candidate) => {
+            const child = relative(sourceDir, candidate);
+            return (child !== '' &&
+                child !== '..' &&
+                !child.startsWith(`..${sep}`) &&
+                !isAbsolute(child));
+        };
+        if (!directory.trim() || isAbsolute(directory) || !confined(path))
+            throw new Error('Excluded directories must be relative paths inside the source root; excluding the source root itself is not allowed');
+        try {
+            if (!confined(await realpath(path)))
+                throw new Error('Excluded directories must stay inside the source root, including symbolic links');
+            if (!(await stat(path)).isDirectory())
+                throw new Error('Excluded paths must name directories inside the source root');
+        }
+        catch (error) {
+            if (!(error &&
+                typeof error === 'object' &&
+                'code' in error &&
+                error.code === 'ENOENT'))
+                throw error;
+        }
+        excludedPaths.add(path);
+    }
+    await mkdir(resolve(options.outDir), { recursive: true });
+    const outDir = await realpath(resolve(options.outDir));
+    if (sourceDir === outDir)
+        throw new Error('Output directory must differ from the source directory');
+    const existing = await readdir(outDir);
+    if (existing.length && !(await isIngestDirectory(outDir))) {
+        throw new Error('Output directory must be empty or previously created by project ingest');
+    }
+    await writeFile(join(outDir, MARKER), `${JSON.stringify({ schemaVersion: SCHEMA })}\n`);
+    const dependencies = await detectDependencies();
+    const available = new Set(dependencies.filter(dep => dep.available).map(dep => dep.command));
+    const summary = {
+        schemaVersion: SCHEMA,
+        sourceDir,
+        outDir,
+        status: 'complete',
+        dependencies,
+        sources: [],
+        images: [],
+        artifacts: [],
+        requestedExcludedDirectories: [...excludedPaths]
+            .map(path => portable(relative(sourceDir, path)))
+            .sort(),
+        excludedDirectories: [],
+        warnings: [],
+        summaryPath: join(outDir, 'summary.json'),
+        textPath: join(outDir, 'text.md'),
+        imagesManifestPath: join(outDir, 'images.json'),
+    };
+    const files = [];
+    async function collect(directory) {
+        const entries = (await readdir(directory, { withFileTypes: true })).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const path = join(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                summary.warnings.push(`Skipped symbolic link: ${portable(relative(sourceDir, path))}`);
+            }
+            else if (entry.isDirectory()) {
+                if (excludedPaths.has(path) ||
+                    path === outDir ||
+                    (await isIngestDirectory(path))) {
+                    summary.excludedDirectories.push(portable(relative(sourceDir, path)));
+                }
+                else
+                    await collect(path);
+            }
+            else if (entry.isFile())
+                files.push(path);
+        }
+    }
+    await collect(sourceDir);
+    const textSections = [
+        '# Extracted project sources',
+        '',
+        'Source facts and byte provenance only. Image filenames and worksheet columns are not semantic or 3D classifications.',
+        '',
+    ];
+    for (const path of files) {
+        const sourceRelativePath = portable(relative(sourceDir, path));
+        options.onProgress?.(`Extracting ${sourceRelativePath}`);
+        const sha256 = await hashFile(path);
+        const format = extname(path).toLowerCase();
+        const source = {
+            relativePath: sourceRelativePath,
+            sha256,
+            byteSize: (await stat(path)).size,
+            format: format.slice(1) || 'unknown',
+            origin: { sourceRoot: sourceDir, relativePath: sourceRelativePath },
+            status: 'complete',
+            artifactPaths: [],
+            warnings: [],
+        };
+        summary.sources.push(source);
+        const key = createHash('sha256')
+            .update(sourceRelativePath)
+            .digest('hex')
+            .slice(0, 16);
+        const folder = join(outDir, 'files', `${key}-${sha256.slice(0, 16)}`);
+        await mkdir(folder, { recursive: true });
+        const origin = { sourceRelativePath, sourceSha256: sha256 };
+        async function artifact(file, kind, detail) {
+            const relativePath = portable(relative(outDir, file));
+            if (relativePath.startsWith('../') || isAbsolute(relativePath))
+                throw new Error('Extraction artifact escaped output directory');
+            const result = {
+                relativePath,
+                sha256: await hashFile(file),
+                byteSize: (await stat(file)).size,
+                kind,
+                origin: { ...origin, ...detail },
+            };
+            summary.artifacts.push(result);
+            source.artifactPaths.push(relativePath);
+            if (kind === 'image')
+                summary.images.push(result);
+        }
+        function needs(...names) {
+            const missing = names.filter(name => !available.has(name));
+            if (!missing.length)
+                return true;
+            source.status = 'partial';
+            source.warnings.push(`Missing dependencies: ${missing.join(', ')}. Install them explicitly and rerun; no installation was attempted.`);
+            return false;
+        }
+        async function readText(file, extraction) {
+            await artifact(file, 'text', { extraction });
+            textSections.push(`## Source: ${sourceRelativePath}`, '', await readFile(file, 'utf8'), '');
+        }
+        try {
+            if (IMAGE_EXTENSIONS.has(format)) {
+                const file = join(folder, `original${format}`);
+                await copyFile(path, file);
+                await artifact(file, 'image', { extraction: 'copy' });
+            }
+            else if (TEXT_EXTENSIONS.has(format)) {
+                const file = join(folder, 'text.txt');
+                await copyFile(path, file);
+                await readText(file, 'text');
+            }
+            else if (format === '.pdf') {
+                if (needs('pdftotext')) {
+                    const file = join(folder, 'text.txt');
+                    await command('pdftotext', ['-layout', path, file]);
+                    await readText(file, 'pdf_text');
+                }
+                if (needs('pdftoppm')) {
+                    await command('pdftoppm', [
+                        '-scale-to',
+                        '1600',
+                        '-png',
+                        path,
+                        join(folder, 'page'),
+                    ]);
+                    const pages = (await readdir(folder))
+                        .filter(name => /^page-\d+\.png$/.test(name))
+                        .sort((a, b) => Number(a.match(/\d+/)?.[0]) - Number(b.match(/\d+/)?.[0]));
+                    for (const page of pages)
+                        await artifact(join(folder, page), 'image', {
+                            extraction: 'pdf_page',
+                            page: Number(page.match(/\d+/)?.[0]),
+                        });
+                }
+            }
+            else if (format === '.xlsx' || format === '.xlsm') {
+                if (needs('python3')) {
+                    await command('python3', [
+                        '-c',
+                        EXTRACT_WORKBOOK_PYTHON,
+                        path,
+                        folder,
+                    ]);
+                    const workbook = JSON.parse(await readFile(join(folder, 'workbook.json'), 'utf8'));
+                    await artifact(join(folder, 'workbook.json'), 'metadata', {
+                        extraction: 'workbook_cells',
+                    });
+                    await readText(join(folder, 'text.txt'), 'workbook_cells');
+                    for (const image of workbook.images) {
+                        await artifact(join(folder, image.file), 'image', {
+                            extraction: 'workbook_media',
+                            workbookMediaPath: image.workbookMediaPath,
+                            placements: image.placements,
+                        });
+                    }
+                    source.warnings.push(...workbook.warnings);
+                    if (workbook.warnings.length)
+                        source.status = 'partial';
+                }
+            }
+            else if (VIDEO_EXTENSIONS.has(format)) {
+                if (needs('ffprobe')) {
+                    const metadataText = await command('ffprobe', [
+                        '-v',
+                        'error',
+                        '-show_format',
+                        '-show_streams',
+                        '-of',
+                        'json',
+                        path,
+                    ]);
+                    const metadataFile = join(folder, 'video.json');
+                    await writeFile(metadataFile, metadataText);
+                    await artifact(metadataFile, 'metadata', {
+                        extraction: 'video_metadata',
+                    });
+                    const metadata = JSON.parse(metadataText);
+                    const video = metadata.streams?.find(stream => stream.codec_type === 'video');
+                    if (!video)
+                        throw new Error('No video stream found');
+                    if (needs('ffmpeg')) {
+                        const duration = Number(video.duration ?? metadata.format?.duration);
+                        const times = Number.isFinite(duration) && duration > 0
+                            ? [0, duration * 0.5, duration * 0.9]
+                            : [0];
+                        if (times.length === 1)
+                            source.warnings.push('Duration unavailable; extracted the first video frame only.');
+                        for (let index = 0; index < times.length; index++) {
+                            const time = Number(times[index].toFixed(6));
+                            const file = join(folder, `frame-${index + 1}.png`);
+                            await command('ffmpeg', [
+                                '-v',
+                                'error',
+                                '-nostdin',
+                                '-y',
+                                '-ss',
+                                String(time),
+                                '-i',
+                                path,
+                                '-map',
+                                '0:v:0',
+                                '-frames:v',
+                                '1',
+                                file,
+                            ]);
+                            await artifact(file, 'image', {
+                                extraction: 'video_frame',
+                                requestedTimestampSeconds: time,
+                            });
+                        }
+                    }
+                }
+                else
+                    needs('ffmpeg');
+            }
+            else {
+                source.status = 'listed';
+            }
+        }
+        catch (error) {
+            source.status = source.artifactPaths.length ? 'partial' : 'failed';
+            source.warnings.push((error instanceof Error ? error.message : String(error)).slice(0, 3000));
+        }
+        if ((await hashFile(path)) !== sha256) {
+            source.status = 'failed';
+            source.warnings.push('Source changed during extraction; provenance is not reliable. Rerun after source changes stop.');
+        }
+        if (source.status === 'partial' || source.status === 'failed')
+            summary.status = 'partial';
+        summary.warnings.push(...source.warnings.map(warning => `${sourceRelativePath}: ${warning}`));
+    }
+    await writeFile(summary.textPath, `${textSections.join('\n')}\n`);
+    await writeFile(summary.imagesManifestPath, `${JSON.stringify({ schemaVersion: SCHEMA, sourceDir, outDir, images: summary.images }, null, 2)}\n`);
+    await writeFile(summary.summaryPath, `${JSON.stringify(summary, null, 2)}\n`);
+    return summary;
+}

package/dist/projectSourcesWorkbook.d.ts

@@ -0,0 +1,3 @@
+/** Standard-library-only helper embedded in the published CLI by TypeScript compilation. */
+export declare const EXTRACT_WORKBOOK_PYTHON: string;
+//# sourceMappingURL=projectSourcesWorkbook.d.ts.map

package/dist/projectSourcesWorkbook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectSourcesWorkbook.d.ts","sourceRoot":"","sources":["../src/projectSourcesWorkbook.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,eAAO,MAAM,uBAAuB,QA6InC,CAAA"}

package/dist/projectSourcesWorkbook.js

@@ -0,0 +1,143 @@
+/** Standard-library-only helper embedded in the published CLI by TypeScript compilation. */
+export const EXTRACT_WORKBOOK_PYTHON = String.raw `
+import json, posixpath, sys, zipfile
+from pathlib import Path
+from xml.etree import ElementTree as E
+
+source, output = Path(sys.argv[1]), Path(sys.argv[2])
+ns = {
+ 's': 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+ 'r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+ 'rd': 'http://schemas.microsoft.com/office/spreadsheetml/2017/richdata',
+ 'xdr': 'http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing',
+ 'a': 'http://schemas.openxmlformats.org/drawingml/2006/main',
+}
+output.mkdir(parents=True, exist_ok=True)
+result = {'sheets': [], 'images': [], 'warnings': []}
+with zipfile.ZipFile(source) as z:
+ names = set(z.namelist())
+ def xml(path):
+  return E.fromstring(z.read(path))
+ def resolve(part, target):
+  return target.lstrip('/') if target.startswith('/') else posixpath.normpath(posixpath.join(posixpath.dirname(part), target))
+ def rels(part):
+  name = posixpath.join(posixpath.dirname(part), '_rels', posixpath.basename(part) + '.rels')
+  if name not in names:
+   return {}
+  return {e.get('Id'): resolve(part, e.get('Target', '')) for e in xml(name) if e.get('TargetMode') != 'External'}
+ def col_name(number):
+  result = ''
+  while number:
+   number, remainder = divmod(number - 1, 26)
+   result = chr(65 + remainder) + result
+  return result
+ strings = []
+ if 'xl/sharedStrings.xml' in names:
+  strings = [''.join(n.text or '' for n in e.iter('{'+ns['s']+'}t')) for e in xml('xl/sharedStrings.xml')]
+ placements = {}
+ def place(target, value):
+  if target in names:
+   placements.setdefault(target, []).append(value)
+  else:
+   result['warnings'].append('Image relationship target is missing: ' + str(target))
+ # Excel rich-value images use cell vm -> value metadata -> future metadata -> rich value -> relationship.
+ rich_paths = ['xl/richData/richValueRel.xml', 'xl/richData/rdrichvalue.xml', 'xl/metadata.xml']
+ rich_targets = {}
+ if all(p in names for p in rich_paths):
+  try:
+   rich_part = rich_paths[0]
+   relationships = rels(rich_part)
+   relation_ids = [e.get('{'+ns['r']+'}id') for e in xml(rich_part)]
+   values = [[e.text for e in row] for row in xml(rich_paths[1])]
+   metadata = xml(rich_paths[2])
+   futures = next(e for e in metadata.findall('s:futureMetadata', ns) if e.get('name') == 'XLRICHVALUE')
+   future_indexes = [int(next(e.iter('{'+ns['rd']+'}rvb')).get('i')) for e in futures]
+   metadata_types = metadata.find('s:metadataTypes', ns)
+   rich_type = next(i+1 for i,e in enumerate(metadata_types) if e.get('name') == 'XLRICHVALUE')
+   local_image_fields = []
+   structure_path = 'xl/richData/rdrichvaluestructure.xml'
+   if structure_path in names:
+    for structure in xml(structure_path):
+     local_image_fields.append(next((i for i,k in enumerate(structure) if k.get('n') == '_rvRel:LocalImageIdentifier'), 0))
+   rich_rows = list(xml(rich_paths[1]))
+   for index, block in enumerate(metadata.find('s:valueMetadata', ns)):
+    rc = next((e for e in block if int(e.get('t', '0')) == rich_type), None)
+    if rc is None:
+     continue
+    value_index = future_indexes[int(rc.get('v'))]
+    structure_index = int(rich_rows[value_index].get('s', '0'))
+    field = local_image_fields[structure_index] if structure_index < len(local_image_fields) else 0
+    relation_index = int(values[value_index][field])
+    rich_targets[index+1] = relationships[relation_ids[relation_index]]
+  except (KeyError, IndexError, ValueError, TypeError, StopIteration) as error:
+   result['warnings'].append('Rich-value cell mapping incomplete: ' + type(error).__name__ + ': ' + str(error))
+ book_rels = rels('xl/workbook.xml')
+ for sheet in xml('xl/workbook.xml').find('s:sheets', ns):
+  name = sheet.get('name', '')
+  part = book_rels[sheet.get('{'+ns['r']+'}id')]
+  document = xml(part)
+  cells = []
+  for cell in document.findall('.//s:sheetData/s:row/s:c', ns):
+   address = cell.get('r')
+   kind = cell.get('t', 'n')
+   value_node = cell.find('s:v', ns)
+   cached = value_node.text if value_node is not None else None
+   if kind == 's' and cached is not None:
+    value = strings[int(cached)]
+   elif kind == 'inlineStr':
+    value = ''.join(n.text or '' for n in cell.findall('.//s:t', ns))
+   else:
+    value = cached
+   formula = cell.find('s:f', ns)
+   record = {'cell': address, 'type': kind, 'value': value}
+   if formula is not None:
+    record['formula'] = formula.text or ''
+   if value is not None or formula is not None:
+    cells.append(record)
+   vm = cell.get('vm')
+   if vm:
+    target = rich_targets.get(int(vm))
+    if target:
+     place(target, {'sheet': name, 'cell': address, 'mapping': 'rich_value_cell'})
+    else:
+     result['warnings'].append('Unresolved image metadata at ' + name + '!' + str(address))
+  result['sheets'].append({'name': name, 'part': part, 'cells': cells})
+  sheet_rels = rels(part)
+  for drawing in document.findall('s:drawing', ns):
+   drawing_part = sheet_rels.get(drawing.get('{'+ns['r']+'}id'))
+   if not drawing_part or drawing_part not in names:
+    result['warnings'].append('Drawing relationship missing in ' + name)
+    continue
+   drawing_rels = rels(drawing_part)
+   for anchor in xml(drawing_part):
+    start = anchor.find('xdr:from', ns)
+    placement = {'sheet': name, 'mapping': 'drawing_anchor'}
+    if start is not None:
+     row = int(start.find('xdr:row', ns).text)+1
+     column = int(start.find('xdr:col', ns).text)+1
+     placement['cell'] = col_name(column) + str(row)
+    for blip in anchor.iter():
+     target = drawing_rels.get(blip.get('{'+ns['r']+'}embed'))
+     if target and target.startswith('xl/media/'):
+      image_placement = placement.copy()
+      if blip.tag.endswith('}imgLayer'):
+       image_placement['mapping'] = 'drawing_image_layer'
+      place(target, image_placement)
+ # Preserve every original media byte, including images whose placement cannot be resolved.
+ for index, media in enumerate(sorted(n for n in names if n.startswith('xl/media/') and not n.endswith('/'))):
+  filename = 'image-' + str(index+1).zfill(4) + Path(media).suffix.lower()
+  (output / filename).write_bytes(z.read(media))
+  result['images'].append({'file': filename, 'workbookMediaPath': media, 'placements': placements.get(media, [])})
+  if media not in placements:
+   result['warnings'].append('Image extracted without cell mapping: ' + media)
+(output / 'workbook.json').write_text(json.dumps(result, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
+lines = []
+for sheet in result['sheets']:
+ lines.append('## Sheet: ' + sheet['name'])
+ for cell in sheet['cells']:
+  value = '' if cell['value'] is None else str(cell['value'])
+  formula = (' [formula: ' + cell['formula'] + ']') if 'formula' in cell else ''
+  lines.append(cell['cell'] + ': ' + value + formula)
+ lines.append('')
+(output / 'text.txt').write_text('\n'.join(lines) + '\n', encoding='utf-8')
+`;

package/dist/runsUpload/artifactGraphModel.d.ts

@@ -0,0 +1,48 @@
+export { canonicalJson, isPlainObject, sha256Hex } from './canonicalJson.js';
+/** `ag.commit.v1` artifact node — output shape of Python `_normalize_artifact`. */
+export type ArtifactNode = {
+    id: string;
+    artifactKind: string;
+    tags: string[];
+    metadata: Record<string, unknown>;
+    semanticType?: string;
+    lifecycle?: string;
+    payload?: Record<string, unknown>;
+    schemaRef?: string;
+    createdBy?: string;
+    createdAt?: string;
+    updatedAt?: string;
+};
+/** Artifact edge — output shape of Python `_normalize_edge`. */
+export type ArtifactEdge = {
+    id: string;
+    from: string;
+    to: string;
+    kind: string;
+    tags: string[];
+    metadata: Record<string, unknown>;
+    createdBy?: string;
+};
+export type ArtifactGraph = {
+    nodes: ArtifactNode[];
+    edges: ArtifactEdge[];
+};
+export declare const codePointCompare: (a: string, b: string) => number;
+/** Port of `_normalize_artifact`: returns null for anything that is not a
+ *  valid `ag.commit.v1` artifact; keeps only the schema's fields. */
+export declare const normalizeArtifact: (value: unknown) => ArtifactNode | null;
+/** Port of `_normalize_edge`. */
+export declare const normalizeEdge: (value: unknown) => ArtifactEdge | null;
+/** Port of `normalize_graph_state`: dedupe by id (last wins), drop edges with
+ *  missing endpoints, sort both arrays by id (code-point order). Idempotent —
+ *  a reader normalizes our JSONL lines and must get them back byte-identical,
+ *  or the manifest hash won't verify. */
+export declare const normalizeArtifactGraph: (value: {
+    nodes?: unknown[];
+    edges?: unknown[];
+} | null) => ArtifactGraph;
+/** Port of `canonical_graph_hash` — callers pass normalizeArtifactGraph output. */
+export declare const canonicalGraphHash: (graph: ArtifactGraph) => string;
+/** Port of `canonical_json_line` (graph_folder/format.py) — one JSONL line. */
+export declare const canonicalJsonLine: (value: unknown) => string;
+//# sourceMappingURL=artifactGraphModel.d.ts.map

package/dist/runsUpload/artifactGraphModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactGraphModel.d.ts","sourceRoot":"","sources":["../../src/runsUpload/artifactGraphModel.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAC,aAAa,EAAE,aAAa,EAAE,SAAS,EAAC,MAAM,oBAAoB,CAAA;AAE1E,mFAAmF;AACnF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,gEAAgE;AAChE,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAAC,KAAK,EAAE,YAAY,EAAE,CAAC;IAAC,KAAK,EAAE,YAAY,EAAE,CAAA;CAAC,CAAA;AAiB1E,eAAO,MAAM,gBAAgB,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAAsC,CAAA;AAmB9F;qEACqE;AACrE,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,YAAY,GAAG,IAqBjE,CAAA;AAED,iCAAiC;AACjC,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,YAAY,GAAG,IAkB7D,CAAA;AAWD;;;yCAGyC;AACzC,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,EAAE,CAAA;CAAC,GAAG,IAAI,KACnD,aAiBF,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,GAAI,OAAO,aAAa,KAAG,MACb,CAAA;AAE7C,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,MAA8B,CAAA"}