🪪 Add id to project frontmatter and populate on init (#934)

* 🪪 Default project id is only uuid

.changeset/neat-dancers-carry.md

@@ -0,0 +1,6 @@
+---
+'myst-frontmatter': patch
+'myst-cli': patch
+---
+
+Add id to project frontmatter and populate on init

docs/frontmatter.md

@@ -139,6 +139,21 @@ The following table lists the available frontmatter fields, a brief description
 * - `options`
   - a dictionary of arbitrary options validated and consumed by templates, for example, during site or PDF build
   - page can override project
+* - `id`
+  - id for the project, intended as a unique identifier as the project is used across different contexts
+  - project only
+* - `references`
+  - configuration for intersphinx references (see [](#intersphinx))
+  - project only
+* - `requirements`
+  - files required for reproducing the executional environment, included in the MECA bundle to enable portable execution
+  - project only
+* - `resources`
+  - other resources associated with your project, distributed in the MECA bundle
+  - project only
+* - `jupyter` or `thebe`
+  - configuration for Jupyter execution (see [](./integrating-jupyter.md))
+  - project only
 ```
 
 +++
@@ -156,6 +171,9 @@ Frontmatter can be attached to a “page”, meaning a local `.md` or `.ipynb` o
 `page can override project`
 : the field is available on both page & project but the value of the field on the page will override any set of the project. Note that the page field must be omitted or undefined, for the project value to be used, value of `null` (or `[]` in the case of `authors`) will still override the project value but clear the field for that page.
 
+`project only`
+: the field is only available on projects, and not present on pages and it will be ignored if set there.
+
 +++
 
 (titles)=

packages/myst-cli/package.json

@@ -100,6 +100,7 @@
     "unist-util-filter": "^4.0.0",
     "unist-util-remove": "^3.1.0",
     "unist-util-select": "^4.0.3",
+    "uuid": "^8.3.2",
     "vfile": "^5.3.5",
     "which": "^3.0.1",
     "ws": "^8.9.0",
@@ -113,6 +114,7 @@
     "@types/fs-extra": "^11.0.1",
     "@types/inquirer": "^9.0.3",
     "@types/mime-types": "^2.1.1",
+    "@types/uuid": "^8.3.4",
     "@types/which": "^3.0.0",
     "@types/ws": "^8.5.5",
     "concurrently": "^8.2.0",

packages/myst-cli/src/build/gh-actions/index.ts

@@ -4,6 +4,7 @@ import inquirer from 'inquirer';
 import chalk from 'chalk';
 import type { ISession } from 'myst-cli-utils';
 import { makeExecutable, writeFileToFolder } from 'myst-cli-utils';
+import { getGithubUrl } from '../utils/github.js';
 
 function createGithubPagesAction({
   defaultBranch = 'main',
@@ -96,19 +97,6 @@ jobs:
 `;
 }
 
-export async function getGithubUrl() {
-  try {
-    const gitUrl = await makeExecutable('git config --get remote.origin.url', null)();
-    if (!gitUrl.includes('github.com')) return undefined;
-    return gitUrl
-      .replace('git@github.com:', 'https://github.com/')
-      .trim()
-      .replace(/\.git$/, '');
-  } catch (error) {
-    return undefined;
-  }
-}
-
 async function checkFolderIsGit(): Promise<boolean> {
   try {
     await makeExecutable('git status', null)();

packages/myst-cli/src/build/init.ts

@@ -1,19 +1,22 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'js-yaml';
+import { v4 as uuid } from 'uuid';
 import { defaultConfigFile, loadConfig, writeConfigs } from '../config.js';
 import { loadProjectFromDisk } from '../project/load.js';
 import { selectors } from '../store/index.js';
 import type { ISession } from '../session/types.js';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import { startServer } from './site/start.js';
-import { getGithubUrl, githubCurvenoteAction, githubPagesAction } from './gh-actions/index.js';
+import { githubCurvenoteAction, githubPagesAction } from './gh-actions/index.js';
+import { getGithubUrl } from './utils/github.js';
 
 const VERSION_CONFIG = '# See docs at: https://mystmd.org/guide/frontmatter\nversion: 1\n';
 
 function createProjectConfig({ github }: { github?: string } = {}) {
   return `project:
+  id: ${uuid()}
   # title:
   # description:
   keywords: []

packages/myst-cli/src/build/utils/github.ts

@@ -0,0 +1,14 @@
+import { makeExecutable } from 'myst-cli-utils';
+
+export async function getGithubUrl() {
+  try {
+    const gitUrl = await makeExecutable('git config --get remote.origin.url', null)();
+    if (!gitUrl.includes('github.com')) return undefined;
+    return gitUrl
+      .replace('git@github.com:', 'https://github.com/')
+      .trim()
+      .replace(/\.git$/, '');
+  } catch (error) {
+    return undefined;
+  }
+}

packages/myst-cli/src/build/utils/index.ts

@@ -5,3 +5,4 @@ export * from './getFileContent.js';
 export * from './localArticleExport.js';
 export * from './resolveAndLogErrors.js';
 export * from './bibtex.js';
+export * from './github.js';

packages/myst-frontmatter/src/project/project.yml

@@ -10,6 +10,7 @@ cases:
     normalized: {}
   - title: full object returns self
     raw:
+      id: my/project
       title: frontmatter
       description: project frontmatter
       venue:
@@ -58,6 +59,7 @@ cases:
       resources:
         - my-script.sh
     normalized:
+      id: my/project
       title: frontmatter
       description: project frontmatter
       venue:

packages/myst-frontmatter/src/project/types.ts

@@ -32,6 +32,7 @@ export const PROJECT_AND_PAGE_FRONTMATTER_KEYS = [
 export const PROJECT_FRONTMATTER_KEYS = [
   ...PROJECT_AND_PAGE_FRONTMATTER_KEYS,
   // These keys only exist on the project
+  'id',
   'references',
   'requirements',
   'resources',
@@ -62,6 +63,7 @@ export type ProjectAndPageFrontmatter = SiteFrontmatter & {
 };
 
 export type ProjectFrontmatter = ProjectAndPageFrontmatter & {
+  id?: string;
   /** Intersphinx and cross-project references */
   references?: Record<string, { url: string }>;
   requirements?: string[];

packages/myst-frontmatter/src/project/validators.ts

@@ -147,6 +147,9 @@ export function validateProjectFrontmatterKeys(
 ) {
   const output: ProjectFrontmatter = validateProjectAndPageFrontmatterKeys(value, opts);
   // This is only for the project, and is not defined on pages
+  if (defined(value.id)) {
+    output.id = validateString(value.id, incrementOptions('id', opts));
+  }
   if (defined(value.references)) {
     const referencesOpts = incrementOptions('references', opts);
     const references = validateObject(value.references, referencesOpts);