@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

package/vendor/l5x/lib/model/xref.js

@@ -0,0 +1,154 @@
+/**
+ * Cross-reference search — which symbols a project's logic references, and where.
+ *
+ * The index is built from decoded ladder NeutralText and Structured Text lines,
+ * not from the raw XML, so a symbol is reported the way a reader of the logic
+ * would write it: `Motor_1.Running` is one symbol and `Motor_1` is also its own
+ * entry, because a caller asking "where is Motor_1 used" expects the dotted
+ * references too.
+ *
+ * Instruction mnemonics and language keywords are excluded — `XIC`, `OTE`, `IF`,
+ * and `AND` are not tags, and reporting them would bury every real answer. The
+ * index is cached per parsed document, so asking one project several questions
+ * scans its logic once.
+ */
+import { splitLines } from "./routines.js";
+/** Ladder instruction mnemonics, which are operators rather than tags. */
+const INSTRUCTION_MNEMONICS = new Set([
+    'XIC', 'XIO', 'OTE', 'OTL', 'OTU', 'TON', 'TOF', 'RTO', 'CTU', 'CTD',
+    'RES', 'MOV', 'ADD', 'SUB', 'MUL', 'DIV', 'NEG', 'CMP', 'EQU', 'NEQ',
+    'GRT', 'GEQ', 'LES', 'LEQ', 'JSR', 'RET', 'SBR', 'AFI', 'NOP', 'MSG',
+    'GSV', 'SSV', 'COP', 'FLL', 'CLR', 'BTD', 'SWPB', 'SIZE',
+]);
+/** Structured Text keywords, which are syntax rather than tags. */
+const STRUCTURED_TEXT_KEYWORDS = new Set([
+    'IF', 'THEN', 'ELSE', 'ELSIF', 'END_IF', 'FOR', 'TO', 'DO', 'END_FOR',
+    'WHILE', 'END_WHILE', 'REPEAT', 'UNTIL', 'END_REPEAT', 'CASE', 'OF',
+    'END_CASE', 'RETURN', 'EXIT', 'NOT', 'AND', 'OR', 'XOR', 'MOD', 'TRUE', 'FALSE',
+]);
+/** Identifiers, including their dotted member paths. */
+const IDENTIFIER = /[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*/g;
+/** Indices already built, keyed by the document they describe. */
+const indices = new WeakMap();
+/**
+ * Search the project's logic for symbols matching a pattern.
+ *
+ * The pattern is a regular expression, evaluated case-insensitively. A pattern
+ * that is not a valid expression is searched for literally instead, so a tag
+ * whose name contains regex punctuation still finds its uses.
+ *
+ * @param document - The parsed project to search.
+ * @param pattern - Regular expression, or literal text when it does not compile.
+ * @returns One entry per matching symbol, in the order the symbols were first
+ * seen, each with every reference to it and an empty result when nothing matched.
+ */
+export function searchLogic(document, pattern) {
+    const matcher = compile(pattern);
+    const results = [];
+    for (const [symbol, references] of indexOf(document)) {
+        if (matcher.test(symbol))
+            results.push({ symbol, references });
+    }
+    return results;
+}
+/** Compile the pattern, falling back to a literal search when it is invalid. */
+function compile(pattern) {
+    try {
+        return new RegExp(pattern, 'i');
+    }
+    catch {
+        return new RegExp(escapeRegExp(pattern), 'i');
+    }
+}
+/** Escape a string so a regular expression matches it literally. */
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** The index for a document, building and caching it on first use. */
+function indexOf(document) {
+    const cached = indices.get(document);
+    if (cached !== undefined)
+        return cached;
+    const built = build(document);
+    indices.set(document, built);
+    return built;
+}
+/** Scan every routine of every program, and each add-on instruction's ladder, for referenced symbols. */
+function build(document) {
+    const index = new Map();
+    for (const routine of document.routines) {
+        if (routine.body.type === 'RLL') {
+            for (const rung of routine.body.rungs) {
+                if (rung.text === '')
+                    continue;
+                for (const symbol of symbolsOf(rung.text, INSTRUCTION_MNEMONICS)) {
+                    add(index, symbol, {
+                        program: routine.program,
+                        routine: routine.name,
+                        rung: rung.number,
+                        context: rung.text,
+                    });
+                }
+            }
+            continue;
+        }
+        if (routine.body.type !== 'ST')
+            continue;
+        for (const line of splitLines(routine.body.code)) {
+            const text = line.text.trim();
+            if (text === '' || text.startsWith('//'))
+                continue;
+            for (const symbol of symbolsOf(line.text, STRUCTURED_TEXT_KEYWORDS)) {
+                add(index, symbol, { program: routine.program, routine: routine.name, line: line.number, context: text });
+            }
+        }
+    }
+    // An add-on instruction's ladder is logic a program runs, so its references
+    // belong in the same index. Its Structured Text is not indexed, matching the
+    // reference engine, which scans only RLL inside an AOI.
+    for (const aoi of document.aois) {
+        for (const routine of aoi.routines) {
+            if (routine.body.type !== 'RLL')
+                continue;
+            for (const rung of routine.body.rungs) {
+                if (rung.text === '')
+                    continue;
+                for (const symbol of symbolsOf(rung.text, INSTRUCTION_MNEMONICS)) {
+                    add(index, symbol, { aoi: aoi.name, routine: routine.name, rung: rung.number, context: rung.text });
+                }
+            }
+        }
+    }
+    return index;
+}
+/** Record one reference under its symbol. */
+function add(index, symbol, reference) {
+    const references = index.get(symbol);
+    if (references === undefined)
+        index.set(symbol, [reference]);
+    else
+        references.push(reference);
+}
+/**
+ * The symbols one piece of logic references.
+ *
+ * A dotted reference contributes both the full path and its base tag, so
+ * searching either finds the use.
+ *
+ * @param text - Ladder NeutralText or one Structured Text line.
+ * @param excluded - Mnemonics or keywords that are not tags.
+ * @returns The symbols, without duplicates.
+ */
+function symbolsOf(text, excluded) {
+    const symbols = new Set();
+    for (const match of text.matchAll(IDENTIFIER)) {
+        const token = match[0];
+        const base = token.split('.')[0];
+        if (base === undefined || excluded.has(base.toUpperCase()))
+            continue;
+        symbols.add(token);
+        if (token.includes('.'))
+            symbols.add(base);
+    }
+    return symbols;
+}

package/vendor/l5x/lib/session.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Open L5X exports for one chat.
+ *
+ * A snapshot names the parsed document, the XML it came from, and the hash of
+ * the bytes. Reads are pure over the document, so a project is parsed once;
+ * every later call re-reads the file only to prove the document is still the
+ * file's content.
+ *
+ * Handles belong to the calling chat. A second chat starts with none open,
+ * which is why an unknown handle names the handles that chat does have.
+ *
+ * @module dsh-engineering-l5x/session
+ */
+import { type L5xDocument } from './model/index.ts';
+import type { ExecContext } from './core/tool.ts';
+import { L5xError } from './core/errors.ts';
+import type { FsService, FsTarget } from './core/tool.ts';
+/** How completely one export feature can be analyzed. */
+export type FeatureLevel = 'analyzed' | 'partial' | 'unsupported' | 'not_present';
+/** One parsed export, identified by the handle the reader passes back. */
+export interface ProjectSnapshot {
+    /** Handle returned by `open_project`. */
+    readonly id: string;
+    /** Path as the caller supplied it. */
+    readonly requestedPath: string;
+    /** Resolved path the filesystem provider returned, for model- and engine-facing output. */
+    readonly path: string;
+    /** Filesystem target used to re-read the export. */
+    readonly target: FsTarget;
+    /** SHA-256 of the bytes this document was parsed from. */
+    readonly sha256: string;
+    /** Size of the export in bytes. */
+    readonly bytes: number;
+    /** Decoded XML text. */
+    readonly xml: string;
+    /** The parsed document. */
+    readonly document: L5xDocument;
+    /** Studio software revision the export declares. */
+    readonly softwareRevision: string;
+    /** Whether this revision is in the parser's observed test matrix. */
+    readonly verification: 'observed_parse' | 'untested_revision';
+    /** Export target type, `Controller` for a full project. */
+    readonly targetType: string;
+    /** Whether the export is a whole controller or one component. */
+    readonly exportKind: 'controller' | 'component';
+    /** Feature analysis level for this export. */
+    readonly features: Readonly<Record<string, FeatureLevel>>;
+    /** ISO timestamp of the open. */
+    readonly openedAt: string;
+}
+/** A failure raised by an analysis engine. */
+export declare class EngineeringError extends L5xError {
+    /**
+     * @param code - Stable identifier for tests and logs.
+     * @param message - What failed, in the reader's terms.
+     * @param fix - The next call or check; defaults to re-reading the project state.
+     */
+    constructor(code: string, message: string, fix?: string);
+}
+/** The parsed-document store, keyed by chat. */
+export declare class ProjectSession {
+    private readonly fs;
+    private readonly maxFileBytes;
+    /** Projects per chat; the key is the calling session object. */
+    private readonly chats;
+    /** Projects for a call without a chat identity, which happens only in tests. */
+    private readonly detached;
+    /**
+     * @param fs - Filesystem provider for the profile.
+     * @param maxFileBytes - Largest export one open will read.
+     */
+    constructor(fs: FsService, maxFileBytes: number);
+    /**
+     * Handles open in the calling chat, in open order.
+     *
+     * @param exec - Calling context; its chat selects the handle set.
+     * @returns The handles that chat can pass to a read.
+     */
+    ids(exec?: ExecContext): readonly string[];
+    /**
+     * Read, parse and retain one export for the calling chat.
+     *
+     * @param requestedPath - Path as the caller supplied it, absolute or relative to the session workspace.
+     * @param exec - Calling context: cancellation, workspace root, and chat identity.
+     * @returns The retained project, including its handle.
+     */
+    open(requestedPath: string, exec?: ExecContext): Promise<ProjectSnapshot>;
+    /**
+     * Resolve the project a read applies to and prove it is still current.
+     *
+     * @param projectId - Explicit handle, or undefined to use the single open project in this chat.
+     * @param exec - Calling context: cancellation and chat identity.
+     * @returns The open project.
+     */
+    require(projectId: string | undefined, exec?: ExecContext): Promise<ProjectSnapshot>;
+    /**
+     * Resolve one path through the filesystem provider without reading it.
+     *
+     * @param requestedPath - Path as the caller supplied it.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns The resolved path.
+     */
+    resolvePath(requestedPath: string, exec?: ExecContext): Promise<string>;
+    /**
+     * Write one prepared draft to a new path, never overwriting.
+     *
+     * @param outputPath - Destination as the caller supplied it.
+     * @param text - The prepared L5X document.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns The resolved destination.
+     */
+    writeNew(outputPath: string, text: string, exec?: ExecContext): Promise<string>;
+    /** The handle set for one calling chat. */
+    private projectsOf;
+    /** The single open project in one chat, or the failure that explains how to choose one. */
+    private single;
+    /** Resolve, check and read one path through the filesystem provider. */
+    private readBytes;
+}

package/vendor/l5x/lib/session.js

@@ -0,0 +1,236 @@
+/**
+ * Open L5X exports for one chat.
+ *
+ * A snapshot names the parsed document, the XML it came from, and the hash of
+ * the bytes. Reads are pure over the document, so a project is parsed once;
+ * every later call re-reads the file only to prove the document is still the
+ * file's content.
+ *
+ * Handles belong to the calling chat. A second chat starts with none open,
+ * which is why an unknown handle names the handles that chat does have.
+ *
+ * @module dsh-engineering-l5x/session
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { L5xParseError, loadL5x } from "./model/index.js";
+import { L5xError } from "./core/errors.js";
+import { decodeExport } from "./fs.js";
+/** A failure raised by an analysis engine. */
+export class EngineeringError extends L5xError {
+    /**
+     * @param code - Stable identifier for tests and logs.
+     * @param message - What failed, in the reader's terms.
+     * @param fix - The next call or check; defaults to re-reading the project state.
+     */
+    constructor(code, message, fix = 'Call project_overview to confirm the project state, then retry.') {
+        super(code, message, fix);
+    }
+}
+/** Most projects one chat retains before the oldest is dropped. */
+const MAX_PROJECTS = 4;
+/** The parsed-document store, keyed by chat. */
+export class ProjectSession {
+    fs;
+    maxFileBytes;
+    /** Projects per chat; the key is the calling session object. */
+    chats = new WeakMap();
+    /** Projects for a call without a chat identity, which happens only in tests. */
+    detached = new Map();
+    /**
+     * @param fs - Filesystem provider for the profile.
+     * @param maxFileBytes - Largest export one open will read.
+     */
+    constructor(fs, maxFileBytes) {
+        this.fs = fs;
+        this.maxFileBytes = maxFileBytes;
+    }
+    /**
+     * Handles open in the calling chat, in open order.
+     *
+     * @param exec - Calling context; its chat selects the handle set.
+     * @returns The handles that chat can pass to a read.
+     */
+    ids(exec) {
+        return [...this.projectsOf(exec).keys()];
+    }
+    /**
+     * Read, parse and retain one export for the calling chat.
+     *
+     * @param requestedPath - Path as the caller supplied it, absolute or relative to the session workspace.
+     * @param exec - Calling context: cancellation, workspace root, and chat identity.
+     * @returns The retained project, including its handle.
+     */
+    async open(requestedPath, exec) {
+        const { bytes, target, displayPath } = await this.readBytes(requestedPath, exec);
+        const xml = decodeExport(bytes);
+        if (/<!DOCTYPE\b|<!ENTITY\b/iu.test(xml)) {
+            throw new L5xError('UNSUPPORTED_XML', 'The export declares a DTD or an entity, which this plugin does not accept.', 'Re-export the project from Studio 5000 without a custom DTD, then reopen it.');
+        }
+        let document;
+        try {
+            document = loadL5x(xml);
+        }
+        catch (error) {
+            throw new L5xError('INVALID_L5X', error instanceof L5xParseError ? error.message : `The file is not a readable L5X export: ${String(error)}`, 'Open a full L5X export from Studio 5000 (File > Save As > L5X), then retry.');
+        }
+        const sha256 = createHash('sha256').update(bytes).digest('hex');
+        const targetType = attribute(xml, 'TargetType');
+        const softwareRevision = attribute(xml, 'SoftwareRevision');
+        const major = Number.parseInt(softwareRevision, 10);
+        if (Number.isFinite(major) && major < 19) {
+            throw new L5xError('UNSUPPORTED_REVISION', `Software revision ${softwareRevision} predates the revision-19 target this parser supports.`, 'Re-export the project from Studio 5000 revision 19 or later, then open that L5X.');
+        }
+        const project = {
+            id: randomUUID(),
+            requestedPath,
+            path: displayPath,
+            target,
+            sha256,
+            bytes: bytes.length,
+            xml,
+            document,
+            softwareRevision,
+            verification: verificationOf(major),
+            targetType,
+            exportKind: targetType === 'Controller' ? 'controller' : 'component',
+            features: featureLevels(xml),
+            openedAt: new Date().toISOString(),
+        };
+        const projects = this.projectsOf(exec);
+        projects.set(project.id, project);
+        while (projects.size > MAX_PROJECTS) {
+            const oldest = projects.keys().next().value;
+            if (oldest !== undefined)
+                projects.delete(oldest);
+        }
+        return project;
+    }
+    /**
+     * Resolve the project a read applies to and prove it is still current.
+     *
+     * @param projectId - Explicit handle, or undefined to use the single open project in this chat.
+     * @param exec - Calling context: cancellation and chat identity.
+     * @returns The open project.
+     */
+    async require(projectId, exec) {
+        const projects = this.projectsOf(exec);
+        const ids = [...projects.keys()];
+        const project = projectId === undefined || projectId === ''
+            ? this.single(ids, projects)
+            : projects.get(projectId);
+        if (project === undefined) {
+            throw new L5xError('UNKNOWN_PROJECT', `No project is open with project_id ${JSON.stringify(projectId)} in this chat.`, ids.length === 0
+                ? 'Call open_project with the L5X path, then retry.'
+                : `Pass one of this chat's open project ids: ${ids.join(', ')}.`, ids);
+        }
+        const bytes = await this.fs.readBytes(project.target, exec?.signal, this.maxFileBytes);
+        const sha256 = createHash('sha256').update(bytes).digest('hex');
+        if (sha256 !== project.sha256) {
+            throw new L5xError('STALE_EXPORT', `The export changed since open_project: ${project.requestedPath}`, 'Call open_project again on the same path, then repeat the read.');
+        }
+        return project;
+    }
+    /**
+     * Resolve one path through the filesystem provider without reading it.
+     *
+     * @param requestedPath - Path as the caller supplied it.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns The resolved path.
+     */
+    async resolvePath(requestedPath, exec) {
+        const target = await this.fs.resolve(requestedPath, {
+            ...(exec?.cwd === undefined ? {} : { cwd: exec.cwd }),
+            ...(exec?.signal === undefined ? {} : { signal: exec.signal }),
+        });
+        return target.displayPath;
+    }
+    /**
+     * Write one prepared draft to a new path, never overwriting.
+     *
+     * @param outputPath - Destination as the caller supplied it.
+     * @param text - The prepared L5X document.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns The resolved destination.
+     */
+    async writeNew(outputPath, text, exec) {
+        if (!/\.l5x$/iu.test(outputPath)) {
+            throw new L5xError('OUTPUT_EXTENSION', 'The draft must be written to an .L5X file.', 'Pass output_path ending in .L5X.');
+        }
+        const target = await this.fs.resolve(outputPath, {
+            ...(exec?.cwd === undefined ? {} : { cwd: exec.cwd }),
+            ...(exec?.signal === undefined ? {} : { signal: exec.signal }),
+        });
+        const info = await this.fs.stat(target, exec?.signal);
+        if (info !== undefined) {
+            throw new L5xError('OUTPUT_EXISTS', `A file already exists at ${outputPath}.`, 'Pass a new output_path; this tool never overwrites an existing file.');
+        }
+        if (this.fs.writeText === undefined) {
+            throw new L5xError('OUTPUT_UNAVAILABLE', 'The filesystem provider in this profile cannot write files.', 'Use a profile whose filesystem provider allows writes, or copy the draft text into Studio manually.');
+        }
+        await this.fs.writeText(target, text, { kind: 'createIfAbsent' }, exec?.signal);
+        return target.displayPath;
+    }
+    /** The handle set for one calling chat. */
+    projectsOf(exec) {
+        const chat = exec?.chat;
+        if (chat === undefined)
+            return this.detached;
+        const existing = this.chats.get(chat);
+        if (existing !== undefined)
+            return existing;
+        const created = new Map();
+        this.chats.set(chat, created);
+        return created;
+    }
+    /** The single open project in one chat, or the failure that explains how to choose one. */
+    single(ids, projects) {
+        const only = ids[0];
+        if (only === undefined) {
+            throw new L5xError('NO_PROJECT', 'No project is open in this chat.', 'Call open_project with the L5X path, then retry.');
+        }
+        if (ids.length > 1) {
+            throw new L5xError('AMBIGUOUS_PROJECT', `${ids.length} projects are open in this chat, so project_id is required.`, `Pass one of this chat's open project ids: ${ids.join(', ')}.`, ids);
+        }
+        return projects.get(only);
+    }
+    /** Resolve, check and read one path through the filesystem provider. */
+    async readBytes(requestedPath, exec) {
+        if (requestedPath.trim() === '') {
+            throw new L5xError('INVALID_ARGUMENT', 'path is required.', 'Pass the L5X file path, for example "C:/Projects/Line/Line.L5X".');
+        }
+        const target = await this.fs.resolve(requestedPath, {
+            ...(exec?.cwd === undefined ? {} : { cwd: exec.cwd }),
+            ...(exec?.signal === undefined ? {} : { signal: exec.signal }),
+        });
+        const info = await this.fs.stat(target, exec?.signal);
+        if (info === undefined) {
+            throw new L5xError('FILE_NOT_FOUND', `No file exists at ${requestedPath}.`, 'Check the path. Use an absolute path or a path inside this workspace, and the .L5X extension.');
+        }
+        if (info.type !== 'file') {
+            throw new L5xError('INVALID_PATH', `${requestedPath} is not a file.`, 'Pass the path of one .L5X export, not a directory.');
+        }
+        return { bytes: await this.fs.readBytes(target, exec?.signal, this.maxFileBytes), target, displayPath: target.displayPath };
+    }
+}
+/** Read one attribute from the export root element. */
+function attribute(xml, name) {
+    const root = /<RSLogix5000Content\b([^>]*)>/u.exec(xml)?.[1] ?? '';
+    return new RegExp(`\\b${name}=["']([^"']*)["']`, 'u').exec(root)?.[1] ?? '';
+}
+/** Revisions the parser has been exercised against; anything else is still read, but flagged. */
+const OBSERVED_REVISIONS = new Set([19, 33, 34, 36, 37]);
+/** Whether a revision is in the observed test matrix. */
+function verificationOf(major) {
+    return OBSERVED_REVISIONS.has(major) ? 'observed_parse' : 'untested_revision';
+}
+/** Feature analysis level for one export. */
+function featureLevels(xml) {
+    return {
+        ladder: 'analyzed',
+        structuredText: 'analyzed',
+        functionBlock: xml.includes('<FBDContent') ? 'partial' : 'not_present',
+        sequentialFunctionChart: xml.includes('<SFCContent') ? 'partial' : 'not_present',
+        alarms: /<Alarm\b|<TagBasedAlarm\b/u.test(xml) ? 'partial' : 'not_present',
+        protectedContent: /<EncodedData\b|Encrypted="true"|SourceProtected="true"/u.test(xml) ? 'unsupported' : 'not_present',
+    };
+}

package/vendor/l5x/lib/skill.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The guidance half of the L5X port.
+ *
+ * `src/index.ts` registers the read tools; this module registers the
+ * `rockwell-l5x` skill that tells a model how to use them. They are separate
+ * loader entries, so a profile can run the tools without the guidance or the
+ * guidance without the tools.
+ *
+ * @module dsh-engineering-l5x/skill
+ */
+/** Plugin name in a composition. */
+export declare const name = "l5x-skill";
+/** Services this plugin cannot register without. */
+export declare const inject: readonly ["skills"];
+/** The plugin context this module needs. */
+export interface SkillContext {
+    get(name: string): unknown;
+}
+/** Registration metadata, kept here so a test can assert it without the file. */
+export declare const SKILL: {
+    readonly name: "rockwell-l5x";
+    readonly description: "Read and review Studio 5000 L5X exports: open a project, list and read components, find references, trace dependencies, resolve addresses, map bit usage, run checks, and compare exports.";
+    readonly whenToUse: "Use when the user asks about a Studio 5000 L5X export, Logix tags, routines, UDTs, AOIs, I/O modules, references, dependency tracing, checks, or comparison between exports.";
+};
+/**
+ * Register the Rockwell L5X skill.
+ *
+ * @param ctx - Plugin context whose skill registry receives the registration.
+ */
+export declare function apply(ctx: SkillContext): void;

package/vendor/l5x/lib/skill.js

@@ -0,0 +1,44 @@
+/**
+ * The guidance half of the L5X port.
+ *
+ * `src/index.ts` registers the read tools; this module registers the
+ * `rockwell-l5x` skill that tells a model how to use them. They are separate
+ * loader entries, so a profile can run the tools without the guidance or the
+ * guidance without the tools.
+ *
+ * @module dsh-engineering-l5x/skill
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/** Plugin name in a composition. */
+export const name = 'l5x-skill';
+/** Services this plugin cannot register without. */
+export const inject = ['skills'];
+/** Registration metadata, kept here so a test can assert it without the file. */
+export const SKILL = {
+    name: 'rockwell-l5x',
+    description: 'Read and review Studio 5000 L5X exports: open a project, list and read components, find references, trace dependencies, resolve addresses, map bit usage, run checks, and compare exports.',
+    whenToUse: 'Use when the user asks about a Studio 5000 L5X export, Logix tags, routines, UDTs, AOIs, I/O modules, references, dependency tracing, checks, or comparison between exports.',
+};
+/**
+ * Register the Rockwell L5X skill.
+ *
+ * @param ctx - Plugin context whose skill registry receives the registration.
+ */
+export function apply(ctx) {
+    const skills = ctx.get('skills');
+    if (skills === undefined || typeof skills.register !== 'function') {
+        throw new Error('l5x-skill: the skills service is unavailable, so the rockwell-l5x guidance cannot register');
+    }
+    const skillPath = fileURLToPath(new URL('../SKILL.md', import.meta.url));
+    const raw = readFileSync(skillPath, 'utf8');
+    const content = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/u, '');
+    skills.register({
+        ...SKILL,
+        content,
+        path: skillPath,
+        source: 'custom',
+        provider: '@aryacode/dsh-engineering-l5x',
+        invocation: { modelInvocable: true, userInvocable: true },
+    });
+}

package/vendor/l5x/lib/studio-state.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Provenance for ACD exports and verified builds, scoped to one chat.
+ *
+ * An ACD export is only usable as a baseline for a later build when this chat
+ * exported that exact L5X from that exact ACD: both hashes must still match.
+ * The record is what makes that check possible without trusting a path.
+ *
+ * @module dsh-engineering-l5x/studio-state
+ */
+import type { ExecContext } from './core/tool.ts';
+import type { DownloadReview } from './engine/download-review.ts';
+/** One SDK build that passed and may be downloaded with its verification id. */
+export interface VerifiedBuild {
+    /** Built ACD path. */
+    readonly path: string;
+    /** SHA-256 of the built ACD at verification time. */
+    readonly sha256: string;
+    /** Baseline L5X the build was reviewed against. */
+    readonly baselinePath: string;
+    /** Edited L5X the build imported. */
+    readonly sourcePath: string;
+    /** Review recorded with the build, including both L5X hashes. */
+    readonly review: Pick<DownloadReview, 'baseline_sha256' | 'source_sha256'>;
+}
+/** One L5X produced by `export_acd_to_l5x`, with the hashes that bind it. */
+export interface AcdExportRecord {
+    /** Resolved ACD that was exported. */
+    readonly acdPath: string;
+    /** Resolved L5X that was written. */
+    readonly l5xPath: string;
+    /** SHA-256 of the ACD bytes at export time. */
+    readonly acdSha256: string;
+    /** SHA-256 of the L5X bytes at export time. */
+    readonly l5xSha256: string;
+}
+/** Exports and verified builds, scoped to the chat that ran them. */
+export declare class StudioState {
+    private readonly chats;
+    private readonly detached;
+    private readonly buildChats;
+    private readonly detachedBuilds;
+    /**
+     * Record one export.
+     *
+     * @param exec - Calling context; its chat owns the record.
+     * @param record - Export binding to remember.
+     */
+    record(exec: ExecContext | undefined, record: AcdExportRecord): void;
+    /**
+     * The export that produced one L5X, if this chat produced it.
+     *
+     * @param exec - Calling context.
+     * @param l5xPath - Resolved L5X path.
+     * @returns The export record, or undefined.
+     */
+    forL5x(exec: ExecContext | undefined, l5xPath: string): AcdExportRecord | undefined;
+    /**
+     * Remember one build that passed and may later be downloaded.
+     *
+     * @param exec - Calling context.
+     * @param id - Verification id returned to the caller.
+     * @param build - Build binding and its review.
+     */
+    addVerified(exec: ExecContext | undefined, id: string, build: VerifiedBuild): void;
+    /**
+     * The build behind one verification id, if this chat produced it.
+     *
+     * @param exec - Calling context.
+     * @param id - Verification id.
+     * @returns The verified build, or undefined.
+     */
+    verified(exec: ExecContext | undefined, id: string): VerifiedBuild | undefined;
+    /** The record map for one calling chat. */
+    private chatsOf;
+    /** The verified-build map for one calling chat. */
+    private buildsOf;
+}