@aryacode/dsh-engineering 0.8.3 → 0.9.0

package/vendor/resources/lib/index.js

@@ -0,0 +1,75 @@
+/**
+ * The engineering resources row: a local standards corpus, a house-style profile
+ * and the `engineering-standards` skill that tells a model to read both before
+ * authoring.
+ *
+ * The corpus is generated data (`index.json`, `SOURCE.json`) over authored
+ * Markdown; the profile is produced by whichever product package has a project
+ * open. This entry only wires them to the tool registry and, when the host offers
+ * it, to the skills service.
+ *
+ * @module dsh-engineering-resources
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resourceTools } from "./tools.js";
+import { getProfile } from "./store.js";
+/** Plugin name in a composition. */
+export const name = 'engineering-resources';
+/** The tools need the registry; the skill is registered when the host offers it. */
+export const inject = ['tools'];
+/** The service name a generation tool can inject to read a profile by handle. */
+export const PROFILES_SERVICE = 'engineeringProfiles';
+/** The skill metadata, kept here so a test can assert it without the file. */
+export const SKILL = {
+    name: 'engineering-standards',
+    description: 'Engineering standards and house style for control code and HMI: read the local corpus for IEC 61131-3, Rockwell, Yaskawa, FactoryTalk and craft rules, profile the open project to follow its own conventions, and cite rule IDs in findings.',
+    whenToUse: 'Before writing or reviewing PLC code, ladder, Structured Text, FactoryTalk View or Optix screens — especially when matching an existing project’s style, or when starting new work that should meet a professional standard.',
+};
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The skill file, in the built package or the source tree. */
+function skillPath() {
+    for (const candidate of [join(HERE, '..', 'SKILL.md'), join(HERE, '..', '..', 'SKILL.md')]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Register the resource tools and the standards skill.
+ *
+ * @param ctx - Plugin context with the tool registry and optional services.
+ * @param config - Row configuration.
+ */
+export function apply(ctx, config = {}) {
+    const getService = (service) => (typeof ctx.get === 'function' ? ctx.get(service) : undefined);
+    if (config.reference !== false) {
+        for (const definition of resourceTools(getService))
+            ctx.tools.register(definition);
+    }
+    ctx.provide?.(PROFILES_SERVICE, { get: getProfile });
+    const path = skillPath();
+    const skills = getService('skills');
+    if (path === undefined || skills?.register === undefined) {
+        try {
+            ctx.logger?.warn?.('engineering-resources: the engineering-standards skill was not registered; the tools are available.');
+        }
+        catch {
+            // A logger that refuses must not turn a missing skill into a crash.
+        }
+        return;
+    }
+    const content = readFileSync(path, 'utf8').replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/u, '');
+    skills.register({
+        ...SKILL,
+        content,
+        path,
+        source: 'custom',
+        provider: '@aryacode/dsh-engineering',
+        invocation: { modelInvocable: true, userInvocable: true },
+    });
+}
+export { getProfile } from "./store.js";
+export { validateProfile, profileId } from "./profile.js";
+export { resourceTools, referenceTool, profileTool } from "./tools.js";

package/vendor/resources/lib/profile.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The house-style profile: the evidence-backed conventions of one open project.
+ *
+ * A profile is produced by a product package (it owns the parser) and validated
+ * here. It is deliberately small JSON: every field names its evidence and the
+ * whole profile carries a confidence level, because a convention inferred from
+ * six rungs is a hint, not a rule.
+ *
+ * @module dsh-engineering-resources/profile
+ */
+/** One counted convention, e.g. a tag prefix. */
+export interface Counted {
+    /** The observed value. */
+    readonly value: string;
+    /** How many times it was observed. */
+    readonly count: number;
+}
+/** Evidence behind one claim. */
+export interface ProfileEvidence {
+    /** File the evidence came from. */
+    readonly file?: string;
+    /** Rung or line number, when the product can name one. */
+    readonly line?: number;
+    /** How many observations support the claim. */
+    readonly count?: number;
+    /** Human-readable note. */
+    readonly note: string;
+}
+/** Kind of project the profile was read from. */
+export type ProfileKind = 'l5x' | 'ftview' | 'mwi' | 'optix';
+/** The profile schema every product returns. */
+export interface StyleProfile {
+    /** Schema version; refuse anything else. */
+    readonly schema: 1;
+    /** Where the profile came from. */
+    readonly source: {
+        readonly kind: ProfileKind;
+        readonly path: string;
+        readonly sha256?: string;
+    };
+    /** Naming conventions, when the product can infer them. */
+    readonly naming?: {
+        readonly tags?: {
+            readonly prefixes: readonly Counted[];
+            readonly case?: string;
+        };
+        readonly routines?: {
+            readonly case?: string;
+            readonly examples?: readonly string[];
+        };
+        readonly displays?: {
+            readonly case?: string;
+            readonly examples?: readonly string[];
+        };
+    };
+    /** Logic idioms the project actually uses. */
+    readonly idioms?: {
+        readonly sealIn?: {
+            readonly count: number;
+            readonly form: string;
+        };
+        readonly latch?: {
+            readonly count: number;
+        };
+        readonly stateMachine?: {
+            readonly count: number;
+            readonly form: string;
+        };
+    };
+    /** HMI conventions, for FactoryTalk View and Optix. */
+    readonly hmi?: {
+        readonly palette?: readonly Counted[];
+        readonly fonts?: readonly Counted[];
+        readonly button?: readonly Counted[];
+        readonly navigation?: {
+            readonly displaysWithNav: number;
+            readonly displays: number;
+        };
+        readonly popups?: {
+            readonly onTop: number;
+            readonly replace: number;
+        };
+    };
+    /** Comment density, where the product exposes comments. */
+    readonly comments?: {
+        readonly total: number;
+        readonly commented: number;
+        readonly ratio: number;
+    };
+    /** What the profile is based on. */
+    readonly evidence: readonly ProfileEvidence[];
+    /** How much to trust it. */
+    readonly confidence: 'low' | 'medium' | 'high';
+}
+/** A validation result: the profile, or the reasons it was refused. */
+export interface ProfileCheck {
+    readonly ok: boolean;
+    readonly problems: readonly string[];
+}
+/**
+ * Validate one profile from a product package.
+ *
+ * @param value - Whatever the product returned.
+ * @returns Ok, or the specific problems.
+ */
+export declare function validateProfile(value: unknown): ProfileCheck;
+/**
+ * A stable handle for one profile, so a tool can refer to it later.
+ *
+ * @param profile - A validated profile.
+ * @returns Short id derived from the source and its digest.
+ */
+export declare function profileId(profile: StyleProfile): string;

package/vendor/resources/lib/profile.js

@@ -0,0 +1,52 @@
+/**
+ * The house-style profile: the evidence-backed conventions of one open project.
+ *
+ * A profile is produced by a product package (it owns the parser) and validated
+ * here. It is deliberately small JSON: every field names its evidence and the
+ * whole profile carries a confidence level, because a convention inferred from
+ * six rungs is a hint, not a rule.
+ *
+ * @module dsh-engineering-resources/profile
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Validate one profile from a product package.
+ *
+ * @param value - Whatever the product returned.
+ * @returns Ok, or the specific problems.
+ */
+export function validateProfile(value) {
+    const problems = [];
+    if (typeof value !== 'object' || value === null)
+        return { ok: false, problems: ['profile is not an object'] };
+    const profile = value;
+    if (profile.schema !== 1)
+        problems.push('schema must be 1');
+    const source = profile.source;
+    if (source === undefined)
+        problems.push('source is required');
+    else {
+        if (!['l5x', 'ftview', 'mwi', 'optix'].includes(source.kind))
+            problems.push(`unknown source.kind ${JSON.stringify(source.kind)}`);
+        if (typeof source.path !== 'string' || source.path === '')
+            problems.push('source.path is required');
+    }
+    if (!['low', 'medium', 'high'].includes(profile.confidence ?? ''))
+        problems.push('confidence must be low, medium or high');
+    if (!Array.isArray(profile.evidence) || profile.evidence.length === 0)
+        problems.push('evidence must be a non-empty array');
+    if (profile.naming === undefined && profile.idioms === undefined && profile.hmi === undefined && profile.comments === undefined) {
+        problems.push('a profile needs at least one of naming, idioms, hmi or comments');
+    }
+    return { ok: problems.length === 0, problems };
+}
+/**
+ * A stable handle for one profile, so a tool can refer to it later.
+ *
+ * @param profile - A validated profile.
+ * @returns Short id derived from the source and its digest.
+ */
+export function profileId(profile) {
+    const seed = JSON.stringify([profile.source.kind, profile.source.path, profile.source.sha256 ?? '', profile.evidence.length]);
+    return createHash('sha256').update(seed).digest('hex').slice(0, 12);
+}

package/vendor/resources/lib/store.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Chat-scoped storage for house-style profiles.
+ *
+ * A profile is produced by a product tool call and consumed by a generation tool
+ * later in the same conversation, so it lives in memory under a short handle. It
+ * is rebuilt from the project whenever the agent asks again; nothing is written
+ * to disk.
+ *
+ * @module dsh-engineering-resources/store
+ */
+import type { StyleProfile } from './profile.ts';
+/**
+ * Remember one profile under its handle.
+ *
+ * @param id - Handle from `profileId`.
+ * @param profile - The validated profile.
+ */
+export declare function rememberProfile(id: string, profile: StyleProfile): void;
+/** The profile for one handle, when it is still in memory. */
+export declare function getProfile(id: string): StyleProfile | undefined;
+/** Drop every profile; tests use this between cases. */
+export declare function clearProfiles(): void;

package/vendor/resources/lib/store.js

@@ -0,0 +1,35 @@
+/**
+ * Chat-scoped storage for house-style profiles.
+ *
+ * A profile is produced by a product tool call and consumed by a generation tool
+ * later in the same conversation, so it lives in memory under a short handle. It
+ * is rebuilt from the project whenever the agent asks again; nothing is written
+ * to disk.
+ *
+ * @module dsh-engineering-resources/store
+ */
+/** Most profiles one process keeps before dropping the oldest. */
+const MAX = 32;
+const profiles = new Map();
+/**
+ * Remember one profile under its handle.
+ *
+ * @param id - Handle from `profileId`.
+ * @param profile - The validated profile.
+ */
+export function rememberProfile(id, profile) {
+    if (profiles.size >= MAX) {
+        const oldest = profiles.keys().next().value;
+        if (oldest !== undefined)
+            profiles.delete(oldest);
+    }
+    profiles.set(id, profile);
+}
+/** The profile for one handle, when it is still in memory. */
+export function getProfile(id) {
+    return profiles.get(id);
+}
+/** Drop every profile; tests use this between cases. */
+export function clearProfiles() {
+    profiles.clear();
+}

package/vendor/resources/lib/tools.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The three resource tools: read the corpus, profile the open project, review a
+ * draft.
+ *
+ * They are deliberately thin. The corpus tool reads generated files; the profile
+ * tool asks the product package that owns the parser; the review tool compares a
+ * product's prepared findings with the profile and the corpus rule IDs.
+ *
+ * @module dsh-engineering-resources/tools
+ */
+import { getProfile } from './store.ts';
+/** The reference tool definition. */
+export declare const referenceTool: {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            id: {
+                type: string;
+                description: string;
+            };
+            domain: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+                minimum: number;
+                maximum: number;
+            };
+        };
+        additionalProperties: boolean;
+        required: never[];
+    };
+    output: {
+        schema: {
+            type: string;
+            additionalProperties: boolean;
+        };
+    };
+    execute(args?: Readonly<Record<string, unknown>>): Promise<unknown>;
+};
+/** The profile tool, bound to the product services the composition provides. */
+export declare function profileTool(getService: (name: string) => unknown): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            project_id: {
+                type: string;
+                description: string;
+            };
+            view_id: {
+                type: string;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+        required: never[];
+    };
+    output: {
+        schema: {
+            type: string;
+            additionalProperties: boolean;
+        };
+    };
+    execute(args?: Readonly<Record<string, unknown>>, exec?: unknown): Promise<unknown>;
+};
+/** Every tool this package registers. */
+export declare function resourceTools(getService: (name: string) => unknown): ({
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            id: {
+                type: string;
+                description: string;
+            };
+            domain: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+                minimum: number;
+                maximum: number;
+            };
+        };
+        additionalProperties: boolean;
+        required: never[];
+    };
+    output: {
+        schema: {
+            type: string;
+            additionalProperties: boolean;
+        };
+    };
+    execute(args?: Readonly<Record<string, unknown>>): Promise<unknown>;
+} | {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            project_id: {
+                type: string;
+                description: string;
+            };
+            view_id: {
+                type: string;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+        required: never[];
+    };
+    output: {
+        schema: {
+            type: string;
+            additionalProperties: boolean;
+        };
+    };
+    execute(args?: Readonly<Record<string, unknown>>, exec?: unknown): Promise<unknown>;
+})[];
+export { getProfile };

package/vendor/resources/lib/tools.js

@@ -0,0 +1,190 @@
+/**
+ * The three resource tools: read the corpus, profile the open project, review a
+ * draft.
+ *
+ * They are deliberately thin. The corpus tool reads generated files; the profile
+ * tool asks the product package that owns the parser; the review tool compares a
+ * product's prepared findings with the profile and the corpus rule IDs.
+ *
+ * @module dsh-engineering-resources/tools
+ */
+import { contents, pageBody, search, corpus } from "./corpus.js";
+import { profileId, validateProfile } from "./profile.js";
+import { getProfile, rememberProfile } from "./store.js";
+/** The failure envelope every engineering tool returns. */
+function failure(error) {
+    const code = typeof error === 'object' && error !== null && typeof error.code === 'string'
+        ? error.code
+        : 'INTERNAL';
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        error: {
+            code,
+            message,
+            fix: code === 'RESOURCES_MISSING'
+                ? 'Run `pnpm resources:build` before packing; the corpus index is generated.'
+                : code === 'COMPONENT_NOT_FOUND'
+                    ? 'Call engineering_reference with no arguments for the available page ids and rule ids.'
+                    : 'Correct the argument and retry; the corpus is local and needs no network.',
+            candidates: [],
+        },
+    };
+}
+/** Coverage carried by every reference answer. */
+const REFERENCE_COVERAGE = {
+    complete: false,
+    unverified: [
+        'whether the advice fits this machine; a profile is evidence, not authority',
+        'the normative text of the standards the pages are based on',
+    ],
+};
+/** Coverage carried by every profile answer. */
+const PROFILE_COVERAGE = {
+    complete: false,
+    unverified: [
+        'runtime behaviour of the inferred conventions',
+        'conventions the parser cannot see (external HMI, undocumented practice)',
+    ],
+};
+/** The reference tool definition. */
+export const referenceTool = {
+    name: 'engineering_reference',
+    description: 'Read the local engineering corpus: return the contents with no arguments, ranked pages for a query, or one page in full for an id. Pages carry rule IDs (CRAFT-NAME-01, VIEW-HPM-02, …) and their basis; nothing is fetched from the network.',
+    parameters: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Topic, rule id or tag to search for, for example "state machine", "VIEW-HPM-02" or "seal-in".' },
+            id: { type: 'string', description: 'Exact page id from the contents, for example "iec-state-machines".' },
+            domain: { type: 'string', description: 'Optional domain filter: iec, rockwell, yaskawa, view, optix or craft.' },
+            limit: { type: 'integer', description: 'Most search hits to return; defaults to 8, maximum 20.', minimum: 1, maximum: 20 },
+        },
+        additionalProperties: false,
+        required: [],
+    },
+    output: { schema: { type: 'object', additionalProperties: true } },
+    async execute(args = {}) {
+        try {
+            const id = typeof args.id === 'string' && args.id.trim() !== '' ? args.id.trim() : undefined;
+            const loaded = corpus();
+            if (id !== undefined) {
+                const row = loaded.index.pages.find(page => page.id === id);
+                if (row === undefined)
+                    throw Object.assign(new Error(`No resource page named "${id}".`), { code: 'COMPONENT_NOT_FOUND' });
+                const markdown = pageBody(id);
+                return {
+                    summary: `Read ${row.title} (${row.domain}, ${row.level}) — rules ${row.rules.join(', ')}.`,
+                    data: {
+                        id,
+                        title: row.title,
+                        domain: row.domain,
+                        level: row.level,
+                        basis: row.basis,
+                        rules: row.rules,
+                        words: row.words,
+                        corpus_digest: loaded.digest,
+                        markdown,
+                    },
+                    next: [{ tool: 'engineering_profile', why: 'Read the open project’s conventions before writing.' }],
+                    coverage: REFERENCE_COVERAGE,
+                };
+            }
+            const query = typeof args.query === 'string' && args.query.trim() !== '' ? args.query.trim() : undefined;
+            if (query === undefined) {
+                const listing = contents();
+                return {
+                    summary: `${loaded.index.pages.length} engineering resource pages across ${listing.domains.length} domains.`,
+                    data: { corpus_digest: loaded.digest, domains: listing.domains, pages: listing.pages },
+                    next: [{ tool: 'engineering_reference', args: { query: 'state machine' }, why: 'Search for the topic you are about to touch.' }],
+                    coverage: REFERENCE_COVERAGE,
+                };
+            }
+            const domain = typeof args.domain === 'string' && args.domain !== '' ? args.domain : undefined;
+            const requested = typeof args.limit === 'number' && Number.isInteger(args.limit) ? args.limit : 8;
+            const hits = search(query, requested, domain);
+            return {
+                summary: hits.length === 0 ? `No resource page matches "${query}".` : `${hits.length} resource page(s) match "${query}".`,
+                data: {
+                    corpus_digest: loaded.digest,
+                    query,
+                    hits,
+                    ...(hits.length === 0 ? { suggestion: 'Call engineering_reference with no arguments for the contents.' } : {}),
+                },
+                next: hits.length === 0
+                    ? [{ tool: 'engineering_reference', why: 'List the contents and pick an id.' }]
+                    : [{ tool: 'engineering_reference', args: { id: hits[0]?.id }, why: 'Read the best-matching page.' }],
+                coverage: REFERENCE_COVERAGE,
+            };
+        }
+        catch (error) {
+            return failure(error);
+        }
+    },
+};
+/** The profile tool, bound to the product services the composition provides. */
+export function profileTool(getService) {
+    return {
+        name: 'engineering_profile',
+        description: 'Read the house style of the open project: naming, logic idioms, HMI palette and fonts, comment density, with the evidence and a confidence level. Call it before authoring so new code follows the plant’s own conventions.',
+        parameters: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string', description: 'L5X project handle from open_project. Omit when exactly one project is open.' },
+                view_id: { type: 'string', description: 'FactoryTalk View handle from ftview_open. Provide this or project_id.' },
+            },
+            additionalProperties: false,
+            required: [],
+        },
+        output: { schema: { type: 'object', additionalProperties: true } },
+        async execute(args = {}, exec) {
+            try {
+                const projectId = typeof args.project_id === 'string' && args.project_id !== '' ? args.project_id : undefined;
+                const viewId = typeof args.view_id === 'string' && args.view_id !== '' ? args.view_id : undefined;
+                const l5x = getService('l5xProjects');
+                const ftview = getService('ftviewViews');
+                const target = viewId !== undefined
+                    ? { service: ftview, id: viewId, name: 'FactoryTalk View' }
+                    : { service: l5x, id: projectId, name: 'L5X' };
+                if (target.service?.styleProfile === undefined) {
+                    return {
+                        error: {
+                            code: 'PROFILE_UNAVAILABLE',
+                            message: `No ${target.name} project service is available in this composition, so a profile cannot be read.`,
+                            fix: viewId !== undefined
+                                ? 'Open the export with ftview_open first, and make sure the ftview row is enabled.'
+                                : 'Open the project with open_project first, and make sure the l5x row is enabled.',
+                            candidates: [],
+                        },
+                    };
+                }
+                const profile = await target.service.styleProfile(target.id, exec);
+                const check = validateProfile(profile);
+                if (!check.ok) {
+                    return {
+                        error: {
+                            code: 'PROFILE_INVALID',
+                            message: `The ${target.name} package returned a profile this version cannot read: ${check.problems.join('; ')}.`,
+                            fix: 'Update the bundle; the profile schema is versioned.',
+                            candidates: [],
+                        },
+                    };
+                }
+                const id = profileId(profile);
+                rememberProfile(id, profile);
+                return {
+                    summary: `${profile.source.kind} profile for ${profile.source.path}: confidence ${profile.confidence}, ${profile.evidence.length} evidence item(s).`,
+                    data: { profile_id: id, profile },
+                    next: [{ tool: 'engineering_reference', query: profile.source.kind === 'ftview' ? 'hmi' : 'state machine', why: 'Read the standard that applies to the change you are about to make.' }],
+                    coverage: PROFILE_COVERAGE,
+                };
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+    };
+}
+/** Every tool this package registers. */
+export function resourceTools(getService) {
+    return [referenceTool, profileTool(getService)];
+}
+export { getProfile };