declapract-typescript-ehmpathy 0.47.19 → 0.47.21

package/dist/.test/infra/withApikeysContext.ts

@@ -0,0 +1,31 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+/**
+ * .what = creates a mock context with apikeys config in a temp directory
+ * .why = enables testing buildWorkflowSecretsBlock with different apikey configs
+ */
+export const withApikeysContext = async (
+  input: { apikeys: string[] },
+  fn: (context: { getProjectRootDirectory: () => string }) => Promise<void>,
+): Promise<void> => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-'));
+  const configDir = path.join(
+    tempDir,
+    '.agent',
+    'repo=.this',
+    'role=any',
+    'skills',
+  );
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(configDir, 'use.apikeys.json'),
+    JSON.stringify({ apikeys: { required: input.apikeys } }, null, 2),
+  );
+  try {
+    await fn({ getProjectRootDirectory: () => tempDir });
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+};

package/dist/practices/cicd-common/best-practice/.agent/repo=.this/role=any/skills/use.apikeys.json.declapract.ts

@@ -0,0 +1,32 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = check that use.apikeys.json exists
+ * .why = enables projects to declare which api keys are required for integration tests
+ */
+export const check = FileCheckType.EXISTS;
+
+/**
+ * .what = creates default use.apikeys.json structure if file doesn't exist
+ * .why = ensures all projects have the config file with proper schema
+ */
+export const fix: FileFixFunction = (contents) => {
+  // if file already exists, preserve its content
+  if (contents) {
+    return { contents };
+  }
+
+  // create default structure
+  return {
+    contents:
+      JSON.stringify(
+        {
+          apikeys: {
+            required: [],
+          },
+        },
+        null,
+        2,
+      ) + '\n',
+  };
+};

package/dist/practices/cicd-common/best-practice/.github/workflows/.test.yml.declapract.ts

@@ -0,0 +1,91 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { readUseApikeysConfig } from '../../../../../utils/readUseApikeysConfig';
+
+/**
+ * .what = builds the expected .test.yml content with apikey secrets injected
+ * .why = single source of truth for both check and fix
+ */
+export const buildExpectedContent = (input: {
+  template: string;
+  apikeys: string[];
+}): string => {
+  let result = input.template;
+
+  // if no apikeys, return template as-is
+  if (!input.apikeys.length) {
+    return result;
+  }
+
+  // build secrets declaration block for workflow_call
+  const secretsDeclaration = input.apikeys
+    .map(
+      (key) =>
+        `      ${key}:\n        description: "api key for ${key.toLowerCase().replace(/_/g, ' ')}"\n        required: false`,
+    )
+    .join('\n');
+
+  // build env block for test-integration job
+  const envBlock = input.apikeys
+    .map((key) => `          ${key}: \${{ secrets.${key} }}`)
+    .join('\n');
+
+  // insert secrets declaration after workflow_call inputs
+  // look for the pattern: inputs: ... (multiline) followed by blank line or permissions:
+  result = result.replace(
+    /(on:\n  workflow_call:\n    inputs:\n(?:      [^\n]+\n)+)/,
+    `$1    secrets:\n${secretsDeclaration}\n\n`,
+  );
+
+  // insert env block to test-integration job
+  // add env block after needs: [install] line
+  result = result.replace(
+    /(test-integration:\n    runs-on: ubuntu-24\.04\n    needs: \[install\]\n)/,
+    `$1    env:\n${envBlock}\n`,
+  );
+
+  return result;
+};
+
+/**
+ * .what = ensures .test.yml matches expected content with apikey secrets
+ * .why = enables integration tests to access required api keys via github secrets
+ */
+export const check: FileCheckFunction = async (contents, context) => {
+  // read apikeys from project
+  const apikeysConfig = await readUseApikeysConfig({
+    projectRootDirectory: context.getProjectRootDirectory(),
+  });
+
+  // build expected content from template + apikeys
+  const expected = buildExpectedContent({
+    template: context.declaredFileContents ?? '',
+    apikeys: apikeysConfig?.apikeys?.required ?? [],
+  });
+
+  // if contents match expected, file passes (throw)
+  if (contents === expected) {
+    throw new Error('file matches expected content');
+  }
+
+  // return = file differs from expected (bad practice detected)
+};
+
+/**
+ * .what = fixes .test.yml to include apikey secrets declaration and env vars
+ * .why = ensures integration tests have access to required api keys
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  // read apikeys from project
+  const apikeysConfig = await readUseApikeysConfig({
+    projectRootDirectory: context.getProjectRootDirectory(),
+  });
+
+  // build expected content from template + apikeys
+  const expected = buildExpectedContent({
+    template: context.declaredFileContents ?? '',
+    apikeys: apikeysConfig?.apikeys?.required ?? [],
+  });
+
+  return { contents: expected };
+};

package/dist/practices/cicd-common/best-practice/.github/workflows/test.yml.declapract.ts

@@ -0,0 +1,40 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+import { buildWorkflowSecretsBlock } from '../../../../../utils/buildWorkflowSecretsBlock';
+
+/**
+ * .what = ensures test.yml matches expected content with apikey secrets block
+ * .why = enables the reusable workflow to access github secrets
+ */
+export const check: FileCheckFunction = async (contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  if (contents === expected) throw new Error('file matches expected content');
+};
+
+/**
+ * .what = fixes test.yml to include apikey secrets block
+ * .why = ensures the reusable workflow receives required api keys
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  return { contents: expected };
+};

package/dist/practices/cicd-package/best-practice/.github/workflows/publish.yml.declapract.ts

@@ -0,0 +1,40 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+import { buildWorkflowSecretsBlock } from '../../../../../utils/buildWorkflowSecretsBlock';
+
+/**
+ * .what = ensures publish.yml matches expected content with apikey secrets block
+ * .why = enables the reusable workflow to access github secrets during publish
+ */
+export const check: FileCheckFunction = async (contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  if (contents === expected) throw new Error('file matches expected content');
+};
+
+/**
+ * .what = fixes publish.yml to include apikey secrets block
+ * .why = ensures the reusable workflow receives required api keys during publish
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  return { contents: expected };
+};

package/dist/practices/cicd-service/best-practice/.github/workflows/deploy.yml.declapract.ts

@@ -0,0 +1,40 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+import { buildWorkflowSecretsBlock } from '../../../../../utils/buildWorkflowSecretsBlock';
+
+/**
+ * .what = ensures deploy.yml matches expected content with apikey secrets block
+ * .why = enables the reusable workflow to access github secrets during deploy
+ */
+export const check: FileCheckFunction = async (contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  if (contents === expected) throw new Error('file matches expected content');
+};
+
+/**
+ * .what = fixes deploy.yml to include apikey secrets block
+ * .why = enables the reusable workflow receives required api keys during deploy
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  // fail fast if template not found
+  if (!context.declaredFileContents)
+    throw new UnexpectedCodePathError('declaredFileContents not found', {
+      relativeFilePath: context.relativeFilePath,
+    });
+
+  const expected = await buildWorkflowSecretsBlock(
+    { template: context.declaredFileContents },
+    context,
+  );
+  return { contents: expected };
+};

package/dist/practices/tests/bad-practices/old-acceptance-dir-location/.declapract.readme.md

@@ -2,7 +2,7 @@
 
 ## .what
 
-detects test files located in `acceptance/` directory and migrates them to `blackbox/`.
+detects test files located in `acceptance/` or `accept.blackbox/` directories and migrates them to `blackbox/`.
 
 ## .why
 
@@ -11,11 +11,11 @@ the term "blackbox" makes the testing philosophy explicit:
 - no access to internal implementation details
 - tests validate behavior from the caller's perspective
 
-the rename from `acceptance/` to `blackbox/` clarifies this intent.
+the rename from `acceptance/` or `accept.blackbox/` to `blackbox/` clarifies this intent and simplifies the naming.
 
 ## .fix
 
-moves all files from `acceptance/` to `blackbox/` while preserving the directory structure.
+moves all files from `acceptance/` or `accept.blackbox/` to `blackbox/` while preserving the directory structure.
 
 ## .note
 

package/dist/practices/tests/bad-practices/old-acceptance-dir-location/accept.blackbox/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if any ts files exist in accept.blackbox/, flag as bad practice
+
+/**
+ * .what = moves ts files from accept.blackbox/ to blackbox/
+ * .why = blackbox/ naming is simpler and makes the testing philosophy explicit
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  // move from accept.blackbox/ to blackbox/
+  const newPath = context.relativeFilePath.replace(
+    /^accept\.blackbox\//,
+    'blackbox/',
+  );
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/utils/buildWorkflowSecretsBlock.ts

@@ -0,0 +1,35 @@
+import { readUseApikeysConfig } from './readUseApikeysConfig';
+
+/**
+ * .what = builds workflow content with apikey secrets block for .test.yml
+ * .why = single source of truth for test.yml, publish.yml, deploy.yml check+fix
+ */
+export const buildWorkflowSecretsBlock = async (
+  input: { template: string },
+  context: { getProjectRootDirectory: () => string },
+): Promise<string> => {
+  // read apikeys from project
+  const apikeysConfig = await readUseApikeysConfig({
+    projectRootDirectory: context.getProjectRootDirectory(),
+  });
+  const apikeys = apikeysConfig?.apikeys?.required ?? [];
+
+  // if no apikeys, return template as-is
+  if (!apikeys.length) {
+    return input.template;
+  }
+
+  // build secrets block
+  const secretsBlock = apikeys
+    .map((key) => `      ${key}: \${{ secrets.${key} }}`)
+    .join('\n');
+
+  // find jobs that call .test.yml with 'with:' block and add secrets block after
+  // handle cases with optional 'if:' before 'with:'
+  const result = input.template.replace(
+    /(uses: \.\/\.github\/workflows\/\.test\.yml\n(?:    if: [^\n]+\n)?    with:\n(?:      [^\n]+\n)+)/g,
+    `$1    secrets:\n${secretsBlock}\n`,
+  );
+
+  return result;
+};

package/dist/utils/readUseApikeysConfig.ts

@@ -0,0 +1,43 @@
+import fs from 'fs';
+import path from 'path';
+import util from 'util';
+
+/**
+ * .what = configuration structure for use.apikeys.json
+ * .why = defines which api keys are required for integration tests
+ */
+export interface UseApikeysConfig {
+  apikeys: {
+    required: string[];
+  };
+}
+
+const USE_APIKEYS_PATH = '.agent/repo=.this/role=any/skills/use.apikeys.json';
+
+/**
+ * .what = reads and parses use.apikeys.json from target project
+ * .why = centralizes apikey config access for all workflow practices
+ */
+export const readUseApikeysConfig = async (input: {
+  projectRootDirectory: string;
+}): Promise<UseApikeysConfig | null> => {
+  // build full path to config file
+  const configPath = path.join(input.projectRootDirectory, USE_APIKEYS_PATH);
+
+  // check if file exists
+  const exists = await util
+    .promisify(fs.access)(configPath, fs.constants.F_OK)
+    .then(() => true)
+    .catch(() => false);
+  if (!exists) return null;
+
+  // read and parse the file
+  try {
+    const contents = await util.promisify(fs.readFile)(configPath, 'utf-8');
+    const parsed = JSON.parse(contents) as UseApikeysConfig;
+    return parsed;
+  } catch {
+    // handle malformed json gracefully
+    return null;
+  }
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.47.19",
+  "version": "0.47.21",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -76,7 +76,7 @@
     "husky": "8.0.3",
     "jest": "30.2.0",
     "rhachet": "1.20.5",
-    "rhachet-roles-bhrain": "0.5.8",
+    "rhachet-roles-bhrain": "0.5.9",
     "rhachet-roles-bhuild": "0.5.6",
     "rhachet-roles-ehmpathy": "1.17.11",
     "tsc-alias": "1.8.10",

package/dist/practices/tests/best-practice/.agent/repo=.this/role=any/skills/use.apikeys.json.declapract.ts

@@ -1,4 +0,0 @@
-import { FileCheckType } from 'declapract';
-
-// check that the file exists; contents are user-defined
-export const check = FileCheckType.EXISTS;