@punal_manalan/blender-project-harness 0.0.0-stage → 1.0.2

package/.kilo/blender-project-harness/tools/harness/documents.mjs

@@ -0,0 +1,201 @@
+const README_SECTIONS = [
+  'Purpose',
+  'What this project is',
+  'Requirements',
+  'Visual direction',
+  'Deliverables',
+  'Project structure',
+  'Blender',
+  'Workflow',
+  'External assets',
+  'Goals',
+  'References',
+  'Open questions',
+  'Next steps',
+];
+
+const GOAL_SECTIONS = [
+  'Mission',
+  'Project',
+  'Visual outcome',
+  'Scope',
+  'Deliverables',
+  'Acceptance',
+  'Workflow',
+  'Done',
+];
+
+export const DOCUMENT_FORMATS = Object.freeze([
+  {
+    id: 'readme',
+    path: 'README.md',
+    fields: ['Status', 'Last updated'],
+    sections: README_SECTIONS,
+  },
+  {
+    id: 'requirements',
+    path: 'Documents/REQUIREMENTS.md',
+    fields: ['Status', 'Defined', 'Last updated', 'Confirmed', 'Confirmation'],
+    sections: ['Core value', 'Confirmed requirements', 'Constraints', 'Deferred', 'Out of scope', 'Open questions', 'Research notes', 'Change log'],
+  },
+  {
+    id: 'workflow',
+    path: 'Documents/WORKFLOW.md',
+    fields: ['Mode', 'Selected', 'Last changed'],
+    sections: ['Current mode', 'Rules', 'Change log'],
+  },
+  {
+    id: 'review',
+    path: 'Documents/REVIEW.md',
+    fields: ['Mode', 'Selected', 'Last changed', 'Single grader'],
+    sections: ['Modes', 'Change log'],
+  },
+  {
+    id: 'assets',
+    path: 'Documents/ASSETS.md',
+    fields: [],
+    sections: ['Rules'],
+  },
+  {
+    id: 'decisions',
+    path: 'Documents/DECISIONS.md',
+    fields: [],
+    sections: [],
+  },
+  {
+    id: 'task-tracker',
+    path: 'Documents/TASKSTRACKER.md',
+    fields: ['Status', 'Last updated'],
+    sections: ['Tasks'],
+  },
+  {
+    id: 'goal',
+    pattern: /^Documents\/Goals\/\d+-[a-z0-9-]+\.md$/,
+    fields: [],
+    sections: GOAL_SECTIONS,
+  },
+  {
+    id: 'documents-index',
+    path: 'Documents/README.md',
+    fields: [],
+    sections: ['Rules'],
+  },
+  {
+    id: 'reviews-index',
+    path: 'Documents/Reviews/README.md',
+    fields: [],
+    sections: ['Index', 'Rules'],
+  },
+  {
+    id: 'references-index',
+    path: 'Documents/References/README.md',
+    fields: [],
+    sections: ['Index'],
+  },
+]);
+
+export function documentFormat(relative) {
+  return DOCUMENT_FORMATS.find((format) => format.path === relative || format.pattern?.test(relative)) ?? null;
+}
+
+export function isBootstrapDocument(relative) {
+  if (typeof relative !== 'string' || !relative.endsWith('.md')) return false;
+  if (relative.startsWith('Documents/Reviews/') && relative !== 'Documents/Reviews/README.md') return false;
+  return true;
+}
+
+export function describeDocumentFormats() {
+  return DOCUMENT_FORMATS.map((format) => ({
+    id: format.id,
+    path: format.path ?? String(format.pattern),
+    fields: [...format.fields],
+    sections: [...format.sections],
+  }));
+}
+
+const field = (text, key) => [...text.matchAll(new RegExp(`^${key}:[ \\t]*([^\\r\\n]*)`, 'gm'))];
+const normalized = (content) => content.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+
+function outline(relative, content) {
+  const text = normalized(content);
+  const lines = text.split('\n');
+  const title = /^#(?!#)[ \t]+(.+?)[ \t]*$/m.exec(text)?.[1] ?? null;
+  const fields = {};
+  const sections = [];
+  let current = null;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    const heading = /^##[ \t]+(.+?)[ \t]*$/.exec(line);
+    if (heading) {
+      current = { heading: heading[1], level: 2, line: index + 1, lines: [] };
+      sections.push(current);
+    } else if (current) current.lines.push(line);
+    else {
+      const match = /^([A-Za-z][A-Za-z0-9 _-]*):[ \t]*(.*)$/.exec(line.trim());
+      if (match) fields[match[1]] = match[2];
+    }
+  }
+  const diagnostics = [];
+  try { validateDocument(relative, content); } catch (error) { diagnostics.push(error.message); }
+  return {
+    title,
+    format: documentFormat(relative)?.id ?? null,
+    fields,
+    sections: sections.map((section) => {
+      const body = section.lines.filter((line) => line.trim());
+      const subheadings = body.map((line) => /^###[ \t]+(.+?)[ \t]*$/.exec(line)?.[1]).filter(Boolean);
+      const excerpt = body.find((line) => !line.startsWith('#'))?.trim().slice(0, 200) ?? '';
+      return { heading: section.heading, line: section.line, lines: body.length, subheadings, excerpt };
+    }),
+    diagnostics,
+    valid: diagnostics.length === 0,
+    bytes: content.length,
+  };
+}
+
+export function documentOutline(relative, content) {
+  if (typeof content !== 'string') throw new Error(`document gate: ${relative} content must be markdown text`);
+  return outline(relative, content);
+}
+
+export function documentSection(relative, content, heading) {
+  if (typeof content !== 'string') throw new Error(`document gate: ${relative} content must be markdown text`);
+  const text = normalized(content);
+  const lines = text.split('\n');
+  const start = lines.findIndex((line) => new RegExp(`^##[ \\t]+${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[ \\t]*$`, 'i').test(line));
+  if (start < 0) return null;
+  const end = lines.findIndex((line, index) => index > start && /^##[ \t]+/.test(line));
+  const body = lines.slice(start + 1, end < 0 ? undefined : end).join('\n').trim();
+  return { heading: lines[start].replace(/^##[ \t]+/, '').trim(), line: start + 1, content: body };
+}
+
+export function validateDocument(relative, content) {
+  if (typeof content !== 'string') throw new Error(`document gate: ${relative} content must be markdown text`);
+  if (!content.trim()) throw new Error(`document gate: ${relative} is empty`);
+  if (content.length > 1_000_000) throw new Error(`document gate: ${relative} exceeds 1,000,000 characters`);
+  const text = normalized(content);
+  if (text.includes('{{')) throw new Error(`document gate: ${relative} contains unresolved template tokens`);
+
+  const headings = [...text.matchAll(/^#(?!#)[ \t]+(.+)$/gm)];
+  if (headings.length !== 1) throw new Error(`document gate: ${relative} requires exactly one level-1 heading`);
+
+  const format = documentFormat(relative);
+  if (!format) return { format: null };
+  for (const name of format.fields) {
+    const matches = field(text, name);
+    if (matches.length !== 1 || !matches[0][1].trim()) throw new Error(`document gate: ${relative} requires exactly one filled ${name}: field`);
+  }
+  for (const name of format.sections) {
+    const count = [...text.matchAll(new RegExp(`^##[ \\t]+${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[ \\t]*$`, 'gm'))].length;
+    if (count !== 1) throw new Error(`document gate: ${relative} requires exactly one "## ${name}" section`);
+  }
+  return { format: format.id };
+}
+
+export const BOOTSTRAP_FILE = /(?:^|\/)(?:\.gitkeep|\.gitignore|\.gitattributes|README\.md|SOURCE\.md|SOURCE_TEMPLATE\.md|LICENSE(?:\.[A-Za-z0-9._-]+)?)$/i;
+
+export function isBootstrapFile(relative) {
+  if (typeof relative !== 'string' || !relative) return false;
+  if (relative.endsWith('.md')) return isBootstrapDocument(relative);
+  return BOOTSTRAP_FILE.test(relative);
+}

package/.kilo/blender-project-harness/tools/harness/download.mjs

@@ -0,0 +1,94 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { classifyIntakeFile, safeIntakeFileName } from './intake.mjs';
+
+export const MAX_DOWNLOAD_BYTES = 512 * 1024 * 1024;
+const MAX_REDIRECTS = 5;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function privateHost(hostname) {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  if (host === 'localhost' || host.endsWith('.localhost') || host === '::1' || host === '0.0.0.0') return true;
+  if (/^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host) || /^169\.254\./.test(host)) return true;
+  const match = /^172\.(\d+)\./.exec(host);
+  if (match && Number(match[1]) >= 16 && Number(match[1]) <= 31) return true;
+  return false;
+}
+
+export function validateDownloadUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { fail('download URL is invalid'); }
+  if (url.protocol !== 'https:') fail('download URL must use HTTPS');
+  if (url.username || url.password) fail('download URL cannot contain credentials');
+  if (privateHost(url.hostname)) fail('download URL cannot target a private or local host');
+  return url;
+}
+
+export function downloadFileName(url, filename) {
+  let name = filename;
+  if (!name) {
+    const pathname = new URL(url).pathname;
+    name = decodeURIComponent(pathname.split('/').filter(Boolean).at(-1) ?? 'download');
+  }
+  if (!classifyIntakeFile(name)) fail('download filename must be a supported asset, reference, script, or image type');
+  return safeIntakeFileName(name, 'download');
+}
+
+function headerFileName(header) {
+  if (!header) return null;
+  const match = /filename\*?=(?:UTF-8''|")?([^";]+)/i.exec(header);
+  return match ? decodeURIComponent(match[1].replace(/"/g, '')) : null;
+}
+
+function stageDirectory(root, project) {
+  const key = String(project ?? 'workspace').replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 80) || 'workspace';
+  return path.join(root, '.temp', 'Intake', key, `${Date.now()}-${crypto.randomUUID().slice(0, 8)}`);
+}
+
+export async function downloadToStaging({ root, project, url, filename, maxBytes = MAX_DOWNLOAD_BYTES } = {}) {
+  const current = validateDownloadUrl(url);
+  if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_DOWNLOAD_BYTES) fail(`maxBytes must be between 1 and ${MAX_DOWNLOAD_BYTES}`);
+  let response;
+  let target = current;
+  for (let redirect = 0; redirect <= MAX_REDIRECTS; redirect += 1) {
+    response = await fetch(target, {
+      redirect: 'manual',
+      signal: AbortSignal.timeout(120_000),
+      headers: { 'user-agent': 'blender-workflow-harness/1.0' },
+    });
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get('location');
+      if (!location) fail('download redirect has no location');
+      target = validateDownloadUrl(new URL(location, target).toString());
+      continue;
+    }
+    break;
+  }
+  if (!response || response.status < 200 || response.status >= 300) fail(`download failed with status ${response?.status ?? 'unknown'}`);
+  const contentType = response.headers.get('content-type') ?? '';
+  if (/^text\/html\b/i.test(contentType) || /^application\/json\b/i.test(contentType)) fail('download returned a document, not an asset');
+  const length = Number(response.headers.get('content-length') ?? 0);
+  if (Number.isFinite(length) && length > maxBytes) fail(`download exceeds maxBytes (${length} > ${maxBytes})`);
+  const buffer = Buffer.from(await response.arrayBuffer());
+  if (buffer.byteLength > maxBytes) fail(`download exceeds maxBytes (${buffer.byteLength} > ${maxBytes})`);
+  const chosen = downloadFileName(target.toString(), filename ?? headerFileName(response.headers.get('content-disposition')));
+  const directory = stageDirectory(root, project);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, chosen);
+  fs.writeFileSync(file, buffer, { mode: 0o600 });
+  return {
+    project: project ?? null,
+    url: target.toString(),
+    path: file,
+    relative: path.relative(root, file).replaceAll('\\', '/'),
+    filename: chosen,
+    bytes: buffer.byteLength,
+    sha256: crypto.createHash('sha256').update(buffer).digest('hex'),
+    contentType,
+    next: 'Call blender_workflow intake with this path and a source/licence record; download alone does not import or execute.',
+  };
+}

package/.kilo/blender-project-harness/tools/harness/download.test.mjs

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { downloadFileName, downloadToStaging, validateDownloadUrl } from './download.mjs';
+
+test('download rejects insecure and private URLs', () => {
+  assert.throws(() => validateDownloadUrl('http://example.com/chair.glb'), /HTTPS/);
+  assert.throws(() => validateDownloadUrl('https://localhost/chair.glb'), /private/);
+  assert.throws(() => validateDownloadUrl('https://127.0.0.1/chair.glb'), /private/);
+  assert.throws(() => validateDownloadUrl('https://10.1.2.3/chair.glb'), /private/);
+  assert.throws(() => validateDownloadUrl('file:///C:/chair.glb'), /HTTPS/);
+  assert.throws(() => validateDownloadUrl('https://user:secret@example.com/chair.glb'), /credentials/);
+  assert.doesNotThrow(() => validateDownloadUrl('https://example.com/chair.glb'));
+});
+
+test('download names only supported files', () => {
+  assert.equal(downloadFileName('https://example.com/files/mood%20board.png'), 'mood-board.png');
+  assert.equal(downloadFileName('https://example.com/download', 'chair.glb'), 'chair.glb');
+  assert.throws(() => downloadFileName('https://example.com/page.html'), /supported/);
+});
+
+test('download stages bytes with a hash and no project write', async (t) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kilo-download-'));
+  t.after(() => fs.rmSync(root, { force: true, recursive: true }));
+  const original = globalThis.fetch;
+  globalThis.fetch = async () => new Response(Buffer.from('glb-bytes'), {
+    status: 200,
+    headers: { 'content-type': 'application/octet-stream', 'content-length': '9' },
+  });
+  t.after(() => { globalThis.fetch = original; });
+  const result = await downloadToStaging({
+    root,
+    project: 'Blender/Test',
+    url: 'https://example.com/chair.glb',
+    filename: 'chair.glb',
+  });
+  assert.equal(result.bytes, 9);
+  assert.equal(result.sha256, '73b18949c3b005215fc7c63efc8c29d5b31ce0760ca9a2f60396cc41b12e970f');
+  assert.match(result.relative, /^\.temp\/Intake\/Blender-Test\//);
+  assert.equal(fs.readFileSync(result.path, 'utf8'), 'glb-bytes');
+  assert.equal(fs.existsSync(path.join(root, 'Blender', 'Test')), false);
+});
+
+test('download refuses oversized responses before staging', async (t) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kilo-download-limit-'));
+  t.after(() => fs.rmSync(root, { force: true, recursive: true }));
+  const original = globalThis.fetch;
+  globalThis.fetch = async () => new Response(Buffer.from('glb-bytes'), {
+    status: 200,
+    headers: { 'content-type': 'application/octet-stream', 'content-length': '9' },
+  });
+  t.after(() => { globalThis.fetch = original; });
+  await assert.rejects(downloadToStaging({
+    root,
+    project: 'Blender/Test',
+    url: 'https://example.com/chair.glb',
+    filename: 'chair.glb',
+    maxBytes: 4,
+  }), /maxBytes/);
+  assert.equal(fs.existsSync(path.join(root, '.temp', 'Intake')), false);
+});