@postman-cse/onboarding-repo-sync 0.11.0 → 0.12.0

package/README.md

@@ -207,8 +207,29 @@ Collections are exported in the Postman Collection v3 format, producing a multi-
 
 The generated CI workflow reads `.postman/resources.yaml` directly to resolve the smoke/contract collection IDs and environment ID for Postman CLI runs. It does not depend on repository variables for those asset mappings.
 
+To match the app scaffold more closely, repo-sync also ensures these directories exist under `postman/`:
+
+- `collections`
+- `environments`
+- `flows`
+- `globals`
+- `mocks`
+- `specs`
+
+It also writes `postman/globals/workspace.globals.yaml` when missing.
+
 Folder and request **names are truncated to 120 characters** per path segment when writing files (with an ellipsis). That avoids `ENAMETOOLONG` when Postman item names are very long (for example, copied from long OpenAPI operation summaries).
 
+### Local spec metadata
+
+Repo-sync now scans the repository for local OpenAPI files and records them in `.postman/resources.yaml` under `localResources.specs`.
+
+- If `spec-path` is provided, it is used as the preferred local spec for `cloudResources.specs` and `.postman/workflows.yaml`.
+- If `spec-path` is omitted and exactly one local OpenAPI file is found, that file is used automatically.
+- If the local spec target is ambiguous or missing, repo-sync skips the spec cloud map and `workflows.yaml` rather than emitting incorrect relationships.
+
+When a local spec file and exported collections are both available, repo-sync writes `.postman/workflows.yaml` with `syncSpecToCollection` entries so the spec↔collection relationship metadata matches the app more closely.
+
 ### Lifecycle and versioning
 
 `collection-sync-mode` controls collection lifecycle behavior:
@@ -234,6 +255,7 @@ Folder and request **names are truncated to 120 characters** per path segment wh
 | `collection-sync-mode` | `refresh` | Collection lifecycle mode: `refresh`, `reuse`, or `version`. |
 | `spec-sync-mode` | `update` | Spec lifecycle mode: `update` or `version`. |
 | `release-label` | | Optional release label for versioned naming. Falls back to `github-ref-name` when omitted. |
+| `spec-path` | | Optional repo-root-relative path to the local spec file for `resources.yaml` and `workflows.yaml` metadata. |
 | `environments-json` | `["prod"]` | Environment slugs to create or update. |
 | `repo-url` | | Explicit repository URL (GitHub or GitLab). Defaults to `https://github.com/$GITHUB_REPOSITORY` on GitHub Actions, or `$CI_PROJECT_URL` on GitLab CI. |
 | `integration-backend` | `bifrost` | Public open-alpha starts with Bifrost only. |

package/action.yml

@@ -134,6 +134,9 @@ inputs:
   spec-id:
     description: Spec UID from bootstrap, persisted into .postman/resources.yaml cloudResources.
     required: false
+  spec-path:
+    description: Optional repo-root-relative path to the local spec file for resources/workflows metadata.
+    required: false
 outputs:
   integration-backend:
     description: Resolved integration backend for the open-alpha run.

package/dist/cli.cjs

@@ -25394,6 +25394,7 @@ function resolveInputs(env = process.env) {
     smokeCollectionId: getInput("smoke-collection-id", env),
     contractCollectionId: getInput("contract-collection-id", env),
     specId: getInput("spec-id", env),
+    specPath: getInput("spec-path", env),
     collectionSyncMode: normalizeCollectionSyncMode(getInput("collection-sync-mode", env) || "refresh"),
     specSyncMode: normalizeSpecSyncMode(getInput("spec-sync-mode", env) || "update"),
     releaseLabel: normalizeReleaseLabel(getInput("release-label", env)) || void 0,
@@ -25469,6 +25470,85 @@ function getEnvironmentUidsFromResources(resourcesState) {
     }).filter((entry) => Boolean(entry))
   );
 }
+function normalizeToPosix(filePath) {
+  return filePath.split(path2.sep).join("/");
+}
+function isOpenApiSpecFile(filePath) {
+  if (!(filePath.endsWith(".json") || filePath.endsWith(".yaml") || filePath.endsWith(".yml"))) {
+    return false;
+  }
+  try {
+    const raw = (0, import_node_fs.readFileSync)(filePath, "utf8");
+    const parsed = filePath.endsWith(".json") ? JSON.parse(raw) : load(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return false;
+    }
+    const doc = parsed;
+    if (doc.swagger === "2.0" && doc.paths && typeof doc.paths === "object") {
+      return true;
+    }
+    if (typeof doc.openapi === "string" && doc.paths && typeof doc.paths === "object") {
+      return true;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+function scanLocalSpecReferences(baseDir = ".") {
+  const ignoredDirs = /* @__PURE__ */ new Set([
+    ".git",
+    ".omc",
+    ".omx",
+    ".llm-plans",
+    "node_modules",
+    "dist"
+  ]);
+  const found = /* @__PURE__ */ new Set();
+  const refs = [];
+  const visit = (currentDir) => {
+    for (const entry of (0, import_node_fs.readdirSync)(currentDir, { withFileTypes: true })) {
+      if (ignoredDirs.has(entry.name)) {
+        continue;
+      }
+      const fullPath = path2.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        visit(fullPath);
+        continue;
+      }
+      if (!entry.isFile() || !isOpenApiSpecFile(fullPath)) {
+        continue;
+      }
+      const repoRelativePath = normalizeToPosix(path2.relative(baseDir, fullPath));
+      if (found.has(repoRelativePath)) {
+        continue;
+      }
+      found.add(repoRelativePath);
+      refs.push({
+        repoRelativePath,
+        configRelativePath: normalizeToPosix(path2.join("..", repoRelativePath))
+      });
+    }
+  };
+  visit(baseDir);
+  return refs.sort((left, right) => left.repoRelativePath.localeCompare(right.repoRelativePath));
+}
+function resolveMappedSpecReference(explicitSpecPath, discoveredSpecs) {
+  const normalizedExplicitPath = normalizeToPosix(explicitSpecPath.trim());
+  if (normalizedExplicitPath) {
+    const explicitFullPath = path2.resolve(normalizedExplicitPath);
+    if ((0, import_node_fs.existsSync)(explicitFullPath) && (0, import_node_fs.statSync)(explicitFullPath).isFile()) {
+      return {
+        repoRelativePath: normalizedExplicitPath,
+        configRelativePath: normalizeToPosix(path2.join("..", normalizedExplicitPath))
+      };
+    }
+  }
+  if (discoveredSpecs.length === 1) {
+    return discoveredSpecs[0];
+  }
+  return void 0;
+}
 function createOutputs(inputs) {
   return {
     "integration-backend": inputs.integrationBackend,
@@ -25688,7 +25768,7 @@ function writeJsonFile(path4, content, normalize2 = false) {
   const data = normalize2 ? stripVolatileFields(content) : content;
   (0, import_node_fs.writeFileSync)(path4, JSON.stringify(data, null, 2));
 }
-function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir, specId) {
+function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir, localSpecRefs, mappedSpecRef, specId) {
   const manifest = {
     workspace: { id: workspaceId }
   };
@@ -25709,9 +25789,11 @@ function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir,
       cloudResources.environments[`../${artifactDir}/environments/${envName}.postman_environment.json`] = envUid;
     }
   }
-  localResources.specs = ["../index.yaml"];
-  if (specId) {
-    cloudResources.specs = { "../index.yaml": specId };
+  if (localSpecRefs.length > 0) {
+    localResources.specs = localSpecRefs;
+  }
+  if (mappedSpecRef && specId) {
+    cloudResources.specs = { [mappedSpecRef]: specId };
   }
   if (Object.keys(localResources).length > 0) {
     manifest.localResources = localResources;
@@ -25725,6 +25807,23 @@ function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir,
     sortKeys: false
   });
 }
+function buildSpecCollectionWorkflowManifest(specRef, collectionRefs) {
+  return dump(
+    {
+      workflows: {
+        syncSpecToCollection: collectionRefs.map((collectionRef) => ({
+          spec: specRef,
+          collection: collectionRef
+        }))
+      }
+    },
+    {
+      lineWidth: -1,
+      noRefs: true,
+      sortKeys: false
+    }
+  );
+}
 function assertPathWithinCwd(targetPath, fieldName) {
   const base = path2.resolve(".");
   const resolved = path2.resolve(base, targetPath);
@@ -25743,15 +25842,27 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName)
   }
   const collectionsDir = `${inputs.artifactDir}/collections`;
   const environmentsDir = `${inputs.artifactDir}/environments`;
+  const flowsDir = `${inputs.artifactDir}/flows`;
+  const globalsDir = `${inputs.artifactDir}/globals`;
   const mocksDir = `${inputs.artifactDir}/mocks`;
+  const specsDir = `${inputs.artifactDir}/specs`;
   ensureDir(collectionsDir);
   ensureDir(environmentsDir);
+  ensureDir(flowsDir);
+  ensureDir(globalsDir);
   ensureDir(mocksDir);
+  ensureDir(specsDir);
   ensureDir(".postman");
+  const globalsFilePath = `${globalsDir}/workspace.globals.yaml`;
+  if (!(0, import_node_fs.existsSync)(globalsFilePath)) {
+    (0, import_node_fs.writeFileSync)(globalsFilePath, "name: Globals\nvalues: []\n");
+  }
   if (inputs.generateCiWorkflow) {
     ensureDir(".github/workflows");
   }
   const manifestCollections = {};
+  const discoveredSpecs = scanLocalSpecReferences();
+  const mappedSpec = resolveMappedSpecReference(inputs.specPath, discoveredSpecs);
   if (inputs.baselineCollectionId) {
     const col = stripVolatileFields(
       await dependencies.postman.getCollection(inputs.baselineCollectionId)
@@ -25788,8 +25899,19 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName)
     manifestCollections,
     envUids,
     inputs.artifactDir,
+    discoveredSpecs.map((spec) => spec.configRelativePath),
+    mappedSpec?.configRelativePath,
     inputs.specId || void 0
   ));
+  if (mappedSpec && Object.keys(manifestCollections).length > 0) {
+    (0, import_node_fs.writeFileSync)(
+      ".postman/workflows.yaml",
+      buildSpecCollectionWorkflowManifest(
+        mappedSpec.configRelativePath,
+        Object.keys(manifestCollections)
+      )
+    );
+  }
 }
 function renderCiWorkflow(inputs) {
   if (inputs.ciWorkflowBase64) {
@@ -26315,6 +26437,7 @@ function parseCliArgs(argv, env = process.env) {
     "ssl-client-passphrase",
     "ssl-extra-ca-certs",
     "spec-id",
+    "spec-path",
     "team-id"
   ];
   const inputEnv = { ...env };

package/dist/index.cjs

@@ -25389,6 +25389,7 @@ function resolveInputs(env = process.env) {
     smokeCollectionId: getInput("smoke-collection-id", env),
     contractCollectionId: getInput("contract-collection-id", env),
     specId: getInput("spec-id", env),
+    specPath: getInput("spec-path", env),
     collectionSyncMode: normalizeCollectionSyncMode(getInput("collection-sync-mode", env) || "refresh"),
     specSyncMode: normalizeSpecSyncMode(getInput("spec-sync-mode", env) || "update"),
     releaseLabel: normalizeReleaseLabel(getInput("release-label", env)) || void 0,
@@ -25464,6 +25465,85 @@ function getEnvironmentUidsFromResources(resourcesState) {
     }).filter((entry) => Boolean(entry))
   );
 }
+function normalizeToPosix(filePath) {
+  return filePath.split(path2.sep).join("/");
+}
+function isOpenApiSpecFile(filePath) {
+  if (!(filePath.endsWith(".json") || filePath.endsWith(".yaml") || filePath.endsWith(".yml"))) {
+    return false;
+  }
+  try {
+    const raw = (0, import_node_fs.readFileSync)(filePath, "utf8");
+    const parsed = filePath.endsWith(".json") ? JSON.parse(raw) : load(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return false;
+    }
+    const doc = parsed;
+    if (doc.swagger === "2.0" && doc.paths && typeof doc.paths === "object") {
+      return true;
+    }
+    if (typeof doc.openapi === "string" && doc.paths && typeof doc.paths === "object") {
+      return true;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+function scanLocalSpecReferences(baseDir = ".") {
+  const ignoredDirs = /* @__PURE__ */ new Set([
+    ".git",
+    ".omc",
+    ".omx",
+    ".llm-plans",
+    "node_modules",
+    "dist"
+  ]);
+  const found = /* @__PURE__ */ new Set();
+  const refs = [];
+  const visit = (currentDir) => {
+    for (const entry of (0, import_node_fs.readdirSync)(currentDir, { withFileTypes: true })) {
+      if (ignoredDirs.has(entry.name)) {
+        continue;
+      }
+      const fullPath = path2.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        visit(fullPath);
+        continue;
+      }
+      if (!entry.isFile() || !isOpenApiSpecFile(fullPath)) {
+        continue;
+      }
+      const repoRelativePath = normalizeToPosix(path2.relative(baseDir, fullPath));
+      if (found.has(repoRelativePath)) {
+        continue;
+      }
+      found.add(repoRelativePath);
+      refs.push({
+        repoRelativePath,
+        configRelativePath: normalizeToPosix(path2.join("..", repoRelativePath))
+      });
+    }
+  };
+  visit(baseDir);
+  return refs.sort((left, right) => left.repoRelativePath.localeCompare(right.repoRelativePath));
+}
+function resolveMappedSpecReference(explicitSpecPath, discoveredSpecs) {
+  const normalizedExplicitPath = normalizeToPosix(explicitSpecPath.trim());
+  if (normalizedExplicitPath) {
+    const explicitFullPath = path2.resolve(normalizedExplicitPath);
+    if ((0, import_node_fs.existsSync)(explicitFullPath) && (0, import_node_fs.statSync)(explicitFullPath).isFile()) {
+      return {
+        repoRelativePath: normalizedExplicitPath,
+        configRelativePath: normalizeToPosix(path2.join("..", normalizedExplicitPath))
+      };
+    }
+  }
+  if (discoveredSpecs.length === 1) {
+    return discoveredSpecs[0];
+  }
+  return void 0;
+}
 function createOutputs(inputs) {
   return {
     "integration-backend": inputs.integrationBackend,
@@ -25683,7 +25763,7 @@ function writeJsonFile(path3, content, normalize2 = false) {
   const data = normalize2 ? stripVolatileFields(content) : content;
   (0, import_node_fs.writeFileSync)(path3, JSON.stringify(data, null, 2));
 }
-function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir, specId) {
+function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir, localSpecRefs, mappedSpecRef, specId) {
   const manifest = {
     workspace: { id: workspaceId }
   };
@@ -25704,9 +25784,11 @@ function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir,
       cloudResources.environments[`../${artifactDir}/environments/${envName}.postman_environment.json`] = envUid;
     }
   }
-  localResources.specs = ["../index.yaml"];
-  if (specId) {
-    cloudResources.specs = { "../index.yaml": specId };
+  if (localSpecRefs.length > 0) {
+    localResources.specs = localSpecRefs;
+  }
+  if (mappedSpecRef && specId) {
+    cloudResources.specs = { [mappedSpecRef]: specId };
   }
   if (Object.keys(localResources).length > 0) {
     manifest.localResources = localResources;
@@ -25720,6 +25802,23 @@ function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir,
     sortKeys: false
   });
 }
+function buildSpecCollectionWorkflowManifest(specRef, collectionRefs) {
+  return dump(
+    {
+      workflows: {
+        syncSpecToCollection: collectionRefs.map((collectionRef) => ({
+          spec: specRef,
+          collection: collectionRef
+        }))
+      }
+    },
+    {
+      lineWidth: -1,
+      noRefs: true,
+      sortKeys: false
+    }
+  );
+}
 function assertPathWithinCwd(targetPath, fieldName) {
   const base = path2.resolve(".");
   const resolved = path2.resolve(base, targetPath);
@@ -25738,15 +25837,27 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName)
   }
   const collectionsDir = `${inputs.artifactDir}/collections`;
   const environmentsDir = `${inputs.artifactDir}/environments`;
+  const flowsDir = `${inputs.artifactDir}/flows`;
+  const globalsDir = `${inputs.artifactDir}/globals`;
   const mocksDir = `${inputs.artifactDir}/mocks`;
+  const specsDir = `${inputs.artifactDir}/specs`;
   ensureDir(collectionsDir);
   ensureDir(environmentsDir);
+  ensureDir(flowsDir);
+  ensureDir(globalsDir);
   ensureDir(mocksDir);
+  ensureDir(specsDir);
   ensureDir(".postman");
+  const globalsFilePath = `${globalsDir}/workspace.globals.yaml`;
+  if (!(0, import_node_fs.existsSync)(globalsFilePath)) {
+    (0, import_node_fs.writeFileSync)(globalsFilePath, "name: Globals\nvalues: []\n");
+  }
   if (inputs.generateCiWorkflow) {
     ensureDir(".github/workflows");
   }
   const manifestCollections = {};
+  const discoveredSpecs = scanLocalSpecReferences();
+  const mappedSpec = resolveMappedSpecReference(inputs.specPath, discoveredSpecs);
   if (inputs.baselineCollectionId) {
     const col = stripVolatileFields(
       await dependencies.postman.getCollection(inputs.baselineCollectionId)
@@ -25783,8 +25894,19 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName)
     manifestCollections,
     envUids,
     inputs.artifactDir,
+    discoveredSpecs.map((spec) => spec.configRelativePath),
+    mappedSpec?.configRelativePath,
     inputs.specId || void 0
   ));
+  if (mappedSpec && Object.keys(manifestCollections).length > 0) {
+    (0, import_node_fs.writeFileSync)(
+      ".postman/workflows.yaml",
+      buildSpecCollectionWorkflowManifest(
+        mappedSpec.configRelativePath,
+        Object.keys(manifestCollections)
+      )
+    );
+  }
 }
 function renderCiWorkflow(inputs) {
   if (inputs.ciWorkflowBase64) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman-cse/onboarding-repo-sync",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Public open-alpha Postman repo sync GitHub Action.",
   "type": "module",
   "main": "dist/index.cjs",