@aopslabs/aops 0.2.0

package/dist/utils/repo-first-view.js

@@ -0,0 +1,305 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeNonEmpty } from './command.js';
+import { parseFrontmatterDocument, renderFrontmatterDocument } from './memory-workspace.js';
+export class ViewSelectorError extends Error {
+    code;
+    selector;
+    candidates;
+    constructor(code, selector, candidates) {
+        super(code === 'ambiguous'
+            ? `Selector "${selector}" is ambiguous.`
+            : `Selector "${selector}" was not found.`);
+        this.name = 'ViewSelectorError';
+        this.code = code;
+        this.selector = selector;
+        this.candidates = candidates;
+    }
+}
+const SYNC_STATES = new Set(['local', 'synced', 'dirty', 'deleted', 'conflict']);
+const DEFAULT_MAX_ITEMS = 25;
+const DEFAULT_MAX_BYTES = 32768;
+const MAX_BYTES_HARD_CAP = 32768;
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function stringValue(value) {
+    return normalizeNonEmpty(value);
+}
+export function numberValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+export function stringArray(value) {
+    return Array.isArray(value)
+        ? value.map((entry) => normalizeNonEmpty(entry)).filter((entry) => Boolean(entry))
+        : [];
+}
+export function recordArray(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+export function normalizeViewStyle(value) {
+    const normalized = normalizeNonEmpty(value);
+    if (normalized === 'compact' || normalized === 'wide')
+        return normalized;
+    return 'agent';
+}
+export function normalizeViewLinkMode(value) {
+    const normalized = normalizeNonEmpty(value);
+    if (normalized === 'relative' || normalized === 'absolute')
+        return normalized;
+    return 'none';
+}
+export function normalizeMaxItems(value) {
+    const parsed = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_MAX_ITEMS;
+    return Math.max(1, Math.min(500, Math.floor(parsed)));
+}
+export function normalizeMaxBytes(value) {
+    const parsed = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_MAX_BYTES;
+    return Math.max(512, Math.min(MAX_BYTES_HARD_CAP, Math.floor(parsed)));
+}
+export function normalizeViewOptions(options = {}) {
+    return {
+        json: options.json === true,
+        style: normalizeViewStyle(options.style),
+        linkMode: normalizeViewLinkMode(options.linkMode),
+        maxItems: normalizeMaxItems(options.maxItems),
+        maxBytes: normalizeMaxBytes(options.maxBytes),
+        includeArchived: options.includeArchived === true,
+    };
+}
+export function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9ğüşöçıİĞÜŞÖÇ]+/gi, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 96) || 'item';
+}
+export function repoRelative(repoRoot, filePath) {
+    return path.relative(repoRoot, filePath).split(path.sep).join('/');
+}
+export async function readMarkdownRecords(rootDir, params = {}) {
+    try {
+        const entries = await fs.readdir(rootDir, { withFileTypes: true });
+        const records = [];
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            const filePath = path.join(rootDir, entry.name);
+            if (entry.isDirectory() && params.recursive === true) {
+                records.push(...await readMarkdownRecords(filePath, params));
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            if (entry.name === 'index.md' && params.includeIndex !== true)
+                continue;
+            const parsed = parseFrontmatterDocument(await fs.readFile(filePath, 'utf8'));
+            records.push({
+                filePath,
+                relativePath: params.repoRoot ? repoRelative(params.repoRoot, filePath) : filePath,
+                frontmatter: parsed.frontmatter,
+                body: parsed.body.trim(),
+            });
+        }
+        return records;
+    }
+    catch {
+        return [];
+    }
+}
+function hashContent(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function comparableRecordHash(record) {
+    const frontmatter = { ...record.frontmatter };
+    delete frontmatter.baseHash;
+    return hashContent(renderFrontmatterDocument(frontmatter, record.body));
+}
+export function effectiveLocalState(record) {
+    const syncState = normalizeNonEmpty(record.frontmatter.syncState);
+    const normalized = syncState && SYNC_STATES.has(syncState) ? syncState : 'local';
+    const baseHash = normalizeNonEmpty(record.frontmatter.baseHash);
+    if (normalized === 'synced' && baseHash && comparableRecordHash(record) !== baseHash)
+        return 'dirty';
+    return normalized;
+}
+export function recordId(record) {
+    return stringValue(record.frontmatter.localId)
+        ?? stringValue(record.frontmatter.id)
+        ?? stringValue(record.frontmatter.remoteId)
+        ?? stringValue(record.frontmatter.memoryId)
+        ?? stringValue(record.frontmatter.documentVersionId)
+        ?? stringValue(record.frontmatter.documentId);
+}
+export function recordLabel(record) {
+    return stringValue(record.frontmatter.name)
+        ?? stringValue(record.frontmatter.title)
+        ?? stringValue(record.frontmatter.slug)
+        ?? recordId(record)
+        ?? record.relativePath;
+}
+export function recordSlug(record) {
+    return stringValue(record.frontmatter.slug)
+        ?? stringValue(record.frontmatter.documentSlug)
+        ?? stringValue(record.frontmatter.groupUid);
+}
+export function idAliases(value) {
+    if (!value)
+        return [];
+    const maybeRecord = value;
+    const frontmatter = isRecord(maybeRecord.frontmatter)
+        ? maybeRecord.frontmatter
+        : value;
+    return [
+        frontmatter.localId,
+        frontmatter.id,
+        frontmatter.remoteId,
+        frontmatter.memoryId,
+        frontmatter.documentId,
+        frontmatter.documentVersionId,
+        frontmatter.topicLocalId,
+        frontmatter.sessionLocalId,
+    ].map((entry) => normalizeNonEmpty(entry)).filter((entry) => Boolean(entry));
+}
+export function sameId(left, aliases) {
+    const normalized = normalizeNonEmpty(left);
+    return Boolean(normalized && aliases.includes(normalized));
+}
+export function matchesEqualCi(value, needle) {
+    const normalized = normalizeNonEmpty(value);
+    return Boolean(normalized && normalized.toLowerCase() === needle.toLowerCase());
+}
+export function matchesAnyEqualCi(values, needle) {
+    return values.some((value) => matchesEqualCi(value, needle));
+}
+export function sameIdOrPrefix(left, aliases) {
+    const normalized = normalizeNonEmpty(left);
+    if (!normalized)
+        return false;
+    if (aliases.includes(normalized))
+        return true;
+    if (normalized.length < 8)
+        return false;
+    return aliases.some((alias) => alias.startsWith(normalized));
+}
+export function candidateFromRecord(record) {
+    return {
+        id: recordId(record),
+        label: recordLabel(record),
+        slug: recordSlug(record),
+        type: stringValue(record.frontmatter.entityType),
+        path: record.relativePath,
+    };
+}
+function selectorFields(record) {
+    const values = [];
+    for (const value of idAliases(record))
+        values.push({ value, kind: 'id' });
+    for (const value of [recordSlug(record), stringValue(record.frontmatter.name), stringValue(record.frontmatter.title)]) {
+        if (value)
+            values.push({ value, kind: value === recordSlug(record) ? 'slug' : 'label' });
+    }
+    values.push({ value: record.relativePath, kind: 'path' });
+    values.push({ value: path.basename(record.relativePath, '.md'), kind: 'slug' });
+    return values;
+}
+export function resolveRecordSelector(records, selector) {
+    const normalized = selector.trim().toLowerCase();
+    if (!normalized) {
+        throw new ViewSelectorError('missing', selector, records.slice(0, 10).map(candidateFromRecord));
+    }
+    const matches = records.filter((record) => selectorFields(record).some(({ value, kind }) => {
+        const candidate = value.toLowerCase();
+        if (candidate === normalized)
+            return true;
+        return kind === 'id' && normalized.length >= 8 && candidate.startsWith(normalized);
+    }));
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw new ViewSelectorError('ambiguous', selector, matches.slice(0, 25).map(candidateFromRecord));
+    }
+    throw new ViewSelectorError('missing', selector, records.slice(0, 25).map(candidateFromRecord));
+}
+function escapeCell(value) {
+    return String(value ?? '')
+        .replace(/\r?\n/g, ' ')
+        .replace(/\|/g, '\\|')
+        .trim();
+}
+export function renderMarkdownTable(headers, rows, options = {}) {
+    const safeHeaders = headers.map(escapeCell);
+    const safeRows = rows.map((row) => row.map(escapeCell));
+    const lines = [
+        `| ${safeHeaders.join(' | ')} |`,
+        `| ${safeHeaders.map(() => '---').join(' | ')} |`,
+    ];
+    for (const row of safeRows) {
+        const padded = safeHeaders.map((_, index) => row[index] ?? '');
+        lines.push(`| ${padded.join(' | ')} |`);
+    }
+    if (rows.length === 0) {
+        const emptyText = escapeCell(options.emptyText ?? 'No matching records.');
+        const cells = safeHeaders.map((_, index) => (index === 0 ? `_${emptyText}_` : ''));
+        lines.push(`| ${cells.join(' | ')} |`);
+    }
+    return lines.join('\n');
+}
+export function shortId(value) {
+    const normalized = normalizeNonEmpty(value);
+    return normalized ? normalized.slice(0, 8) : '-';
+}
+export function formatDate(value) {
+    const normalized = normalizeNonEmpty(value);
+    if (!normalized)
+        return '-';
+    const date = new Date(normalized);
+    if (Number.isNaN(date.getTime()))
+        return normalized;
+    return date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+export function summarizeText(value, maxLength = 120) {
+    const compact = String(value ?? '').replace(/\s+/g, ' ').trim();
+    if (!compact)
+        return '-';
+    if (compact.length <= maxLength)
+        return compact;
+    return `${compact.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+export function renderKeyValues(values) {
+    return values
+        .filter(([, value]) => value !== undefined && value !== null && String(value).trim() !== '')
+        .map(([label, value]) => `- ${label}: ${String(value)}`)
+        .join('\n');
+}
+export function applyMaxBytes(markdown, maxBytes) {
+    const limit = normalizeMaxBytes(maxBytes);
+    const bytes = Buffer.byteLength(markdown, 'utf8');
+    if (bytes <= limit)
+        return { markdown, truncated: false };
+    const footer = `\n\n---\n\nTruncated: output exceeded ${limit} bytes. Use --max-items or a narrower selector.\n`;
+    const target = Math.max(0, limit - Buffer.byteLength(footer, 'utf8'));
+    let sliced = markdown;
+    while (Buffer.byteLength(sliced, 'utf8') > target && sliced.length > 0) {
+        sliced = sliced.slice(0, Math.floor(sliced.length * 0.9));
+    }
+    return { markdown: `${sliced.trimEnd()}${footer}`, truncated: true };
+}
+export function renderFooter(params) {
+    return [
+        '',
+        '---',
+        '',
+        renderKeyValues([
+            ['source', params.source],
+            ['local-state', params.localState ?? '-'],
+            ['updatedAt', formatDate(params.updatedAt)],
+            ['lastPushedAt', formatDate(params.lastPushedAt)],
+            ['lastPulledAt', formatDate(params.lastPulledAt)],
+            ['truncated', params.truncated === true ? 'true' : 'false'],
+        ]),
+    ].join('\n');
+}

package/dist/utils/session-guidance.js

@@ -0,0 +1,278 @@
+import path from 'node:path';
+import { compactPayload, normalizeNonEmpty } from './command.js';
+import { readExperienceItems, resolveExperienceWorkspacePaths } from './experience-workspace.js';
+const DEFAULT_EXPERIENCE_LIMIT = 3;
+const MAX_EXPERIENCE_LIMIT = 5;
+function parseLimit(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+        return Math.min(Math.trunc(value), MAX_EXPERIENCE_LIMIT);
+    }
+    const normalized = normalizeNonEmpty(value);
+    if (!normalized)
+        return DEFAULT_EXPERIENCE_LIMIT;
+    const parsed = Number.parseInt(normalized, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_EXPERIENCE_LIMIT;
+    return Math.min(Math.trunc(parsed), MAX_EXPERIENCE_LIMIT);
+}
+function summarizeContent(content, maxLength = 180) {
+    const compact = normalizeNonEmpty(content)?.replace(/\s+/g, ' ');
+    if (!compact)
+        return undefined;
+    if (compact.length <= maxLength)
+        return compact;
+    return `${compact.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+function tokenize(value) {
+    const normalized = normalizeNonEmpty(value)?.toLowerCase();
+    if (!normalized)
+        return [];
+    return [...new Set(normalized.split(/[^a-z0-9]+/).filter((token) => token.length >= 3))];
+}
+function sourceRefsContain(item, expected) {
+    if (!expected)
+        return false;
+    return item.sourceRefs.some((ref) => {
+        if (!ref || typeof ref !== 'object' || Array.isArray(ref))
+            return false;
+        const record = ref;
+        const refId = normalizeNonEmpty(record.refId) ?? normalizeNonEmpty(record.id);
+        return refId === expected;
+    });
+}
+function scoreExperience(item, options) {
+    const reasons = [];
+    let score = 0;
+    const area = normalizeNonEmpty(options.area)?.toLowerCase();
+    const taskTokens = tokenize(options.task);
+    const haystackParts = [
+        item.title,
+        item.problem,
+        item.solution,
+        item.content,
+        ...item.areas,
+        ...item.stack,
+        ...item.tags,
+        ...item.commands,
+        ...item.files,
+    ].map((entry) => normalizeNonEmpty(entry)?.toLowerCase()).filter((entry) => Boolean(entry));
+    const haystack = haystackParts.join(' ');
+    if (area && item.areas.some((entry) => entry.toLowerCase() === area)) {
+        score += 30;
+        reasons.push(`area:${area}`);
+    }
+    if (sourceRefsContain(item, options.missionId)) {
+        score += 25;
+        reasons.push('mission-ref');
+    }
+    if (sourceRefsContain(item, options.planId)) {
+        score += 20;
+        reasons.push('plan-ref');
+    }
+    for (const token of taskTokens) {
+        if (haystack.includes(token)) {
+            score += 4;
+            reasons.push(`task:${token}`);
+        }
+    }
+    if (item.confidence?.toLowerCase() === 'high') {
+        score += 3;
+        reasons.push('confidence:high');
+    }
+    if (item.reusability?.toLowerCase() === 'high') {
+        score += 2;
+        reasons.push('reusability:high');
+    }
+    return { score, reasons };
+}
+function toExperienceBrief(item, score, reasons) {
+    return {
+        id: item.localId,
+        title: item.title,
+        type: item.type,
+        areas: item.areas,
+        stack: item.stack,
+        tags: item.tags,
+        confidence: item.confidence,
+        score,
+        scoreReasons: reasons,
+        updatedAt: item.updatedAt,
+        contentPreview: summarizeContent(item.content),
+    };
+}
+async function buildExperienceBriefs(context, options) {
+    const paths = resolveExperienceWorkspacePaths({ repoRoot: context.repoRoot, localRoot: context.localRoot });
+    const limit = parseLimit(options.limit);
+    const items = await readExperienceItems(paths.itemsDir);
+    return items
+        .map((item) => {
+        const scored = scoreExperience(item, options);
+        return { item, ...scored };
+    })
+        .filter((entry) => entry.score > 0 || normalizeNonEmpty(options.area) === undefined)
+        .sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        const updated = right.item.updatedAt.localeCompare(left.item.updatedAt);
+        if (updated !== 0)
+            return updated;
+        return left.item.localId.localeCompare(right.item.localId);
+    })
+        .slice(0, limit)
+        .map((entry) => toExperienceBrief(entry.item, entry.score, entry.reasons));
+}
+function flattenPlaybookBriefs(playbookNudges) {
+    if (!playbookNudges)
+        return [];
+    const data = [...playbookNudges.project.data, ...playbookNudges.session.data];
+    return data.slice(0, MAX_EXPERIENCE_LIMIT);
+}
+function readOnlyPlaybookActions(playbookNudges) {
+    return (playbookNudges?.suggestedActions ?? []).filter((action) => action.applyRequired === false);
+}
+function runtimeLayer(context, options) {
+    return {
+        id: 'L1-runtime-session-rules',
+        items: [
+            {
+                id: 'agents-md',
+                title: 'Project AGENTS.md and local operator instructions',
+                source: path.relative(context.repoRoot, path.join(context.repoRoot, 'AGENTS.md')).split(path.sep).join('/'),
+                required: true,
+                note: 'Read project runtime rules before acting; they define owner boundaries, PM discipline, and repo-local constraints.',
+            },
+            {
+                id: 'chatv3-room-rules',
+                title: 'ChatV3 channel and room guidance',
+                source: 'chatv3.guidanceMarkdown',
+                required: options.surface === 'start-reminder',
+                note: 'When a hosted room is active, read room rules and latest messages; chat is coordination, PM/discuss/memory remain truth ledgers.',
+            },
+            {
+                id: 'operator-current-instruction',
+                title: 'Current operator instruction',
+                source: 'current prompt or latest chat directive',
+                required: true,
+                note: 'Newest operator instruction wins when it conflicts with older session context.',
+            },
+        ],
+    };
+}
+function disciplineLayer(input) {
+    if (!input)
+        return undefined;
+    return {
+        id: 'L2-working-discipline-guardrails',
+        selected: normalizeNonEmpty(input.selected),
+        recommended: normalizeNonEmpty(input.recommended),
+        explicit: input.explicit,
+        profile: input.profile
+            ? compactPayload({
+                id: normalizeNonEmpty(input.profile.id),
+                version: normalizeNonEmpty(input.profile.version),
+                title: normalizeNonEmpty(input.profile.title),
+            })
+            : undefined,
+        guardrails: (input.guardrails ?? []).map((guardrail) => compactPayload({
+            id: normalizeNonEmpty(guardrail.id),
+            title: normalizeNonEmpty(guardrail.title),
+            phase: normalizeNonEmpty(guardrail.phase),
+            enforcementLevel: normalizeNonEmpty(guardrail.enforcementLevel),
+        })),
+    };
+}
+function buildSuggestedActions(params) {
+    const projectSlug = normalizeNonEmpty(params.context.projectSlug);
+    const area = normalizeNonEmpty(params.options.area);
+    const task = normalizeNonEmpty(params.options.task);
+    return [
+        {
+            kind: 'read-runtime-rules',
+            mode: 'read-only',
+            applyRequired: false,
+            command: 'Read AGENTS.md in the active repo before implementation.',
+        },
+        ...readOnlyPlaybookActions(params.playbookNudges).map((action) => ({
+            ...action,
+            mode: 'read-only',
+            applyRequired: false,
+        })),
+        {
+            kind: 'inspect-experience',
+            mode: 'read-only',
+            applyRequired: false,
+            command: [
+                'aops-cli view experience',
+                projectSlug ? `--project-slug ${projectSlug}` : undefined,
+                area ? `--area ${area}` : undefined,
+                '--json',
+            ].filter(Boolean).join(' '),
+            note: task
+                ? 'Use ranked experience briefs first, then inspect the full view only if the task still needs more context.'
+                : 'Inspect repo-first experience only when the reminder pack is not enough.',
+        },
+    ];
+}
+export async function buildSessionGuidancePack(context, options) {
+    const missionId = normalizeNonEmpty(options.missionId);
+    const planId = normalizeNonEmpty(options.planId);
+    const area = normalizeNonEmpty(options.area);
+    const task = normalizeNonEmpty(options.task);
+    const experience = await buildExperienceBriefs(context, options);
+    const playbookData = flattenPlaybookBriefs(options.playbookNudges);
+    const suggestedActions = buildSuggestedActions({ context, options, playbookNudges: options.playbookNudges });
+    return {
+        schemaVersion: 1,
+        mode: 'session-guidance-pack',
+        surface: options.surface,
+        readOnly: true,
+        defaultWrite: false,
+        hints: compactPayload({
+            task,
+            missionId,
+            planId,
+            area,
+            experienceLimit: parseLimit(options.limit),
+        }),
+        layers: compactPayload({
+            runtime: runtimeLayer(context, options),
+            discipline: disciplineLayer(options.discipline),
+            playbooks: {
+                id: 'L3-accepted-playbook-briefs',
+                readOnly: true,
+                defaultWrite: false,
+                count: playbookData.length,
+                projectCount: options.playbookNudges?.project.count ?? 0,
+                sessionCount: options.playbookNudges?.session.count ?? 0,
+                data: playbookData,
+                suggestedActions: readOnlyPlaybookActions(options.playbookNudges),
+                note: 'Accepted playbooks are guidance only; start/reminder/resume never promote, capture, or mutate playbooks.',
+            },
+            experience: {
+                id: 'L3-ranked-experience-briefs',
+                mode: 'repo-first-experience-briefs',
+                readOnly: true,
+                defaultWrite: false,
+                filters: compactPayload({
+                    area,
+                    task,
+                    missionId,
+                    planId,
+                    limit: parseLimit(options.limit),
+                    maxLimit: MAX_EXPERIENCE_LIMIT,
+                }),
+                count: experience.length,
+                data: experience,
+                note: 'Experience briefs are deterministic repo-first reads ranked by area, source refs, task token matches, confidence, recency, then id.',
+            },
+        }),
+        suggestedActions,
+        constraints: [
+            'read-only',
+            'defaultWrite=false',
+            'no checkpoint, PM, chat, experience, memory, or playbook mutation',
+            'bounded experience briefs: default 3, max 5',
+            'start --reminder does not require board, room, roles, or full kickoff prompt rendering',
+        ],
+    };
+}