feat(api): creation of a new list command (#775)

* feat(api): creation of a new `list` command * Update packages/api/src/commands/list.ts Co-authored-by: Kanad Gupta <[email protected]> * Update packages/api/src/commands/list.ts Co-authored-by: Kanad Gupta <[email protected]> * Update packages/api/src/commands/list.ts Co-authored-by: Kanad Gupta <[email protected]> * fix: pr feedback --------- Co-authored-by: Kanad Gupta <[email protected]>
readmeio · Oct 19, 2023 · a8b9891 · a8b9891
1 parent e2b1df9
commit a8b9891
Show file tree

Hide file tree

Showing 7 changed files with 162 additions and 18 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/api/package.json b/packages/api/package.json
@@ -77,6 +77,7 @@
     "@types/validate-npm-package-name": "^4.0.0",
     "@vitest/coverage-v8": "^0.34.4",
     "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1",
     "fetch-mock": "^9.11.0",
     "oas-normalize": "^11.0.1",
     "tsup": "^7.2.0",

diff --git a/packages/api/schema.json b/packages/api/schema.json
@@ -3,25 +3,31 @@
   "title": "api storage lockfile",
   "description": "See https://api.readme.dev/docs",
   "type": "object",
-  "required": ["apis", "version"],
+  "required": ["apis"],
+  "additionalProperties": false,
   "properties": {
+    "$schema": {
+      "type": "string"
+    },
     "apis": {
       "type": "array",
       "description": "The list of installed APIs",
       "items": {
         "$ref": "#/definitions/api"
       }
-    },
-    "version": {
-      "type": "string",
-      "description": "The current `api.json` schema version."
     }
   },
   "definitions": {
     "api": {
       "type": "object",
-      "required": ["identifier", "installerVersion", "integrity"],
+      "required": ["createdAt", "identifier", "installerVersion", "integrity"],
       "properties": {
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "The date that this SDK was installed.",
+          "examples": ["2023-10-19T20:35:39.268Z"]
+        },
         "identifier": {
           "type": "string",
           "description": "A unique identifier of the API. This'll be used to do imports on `@api/<identifier>` and also where the SDK code will be located in `.api/apis/<identifier>`",
@@ -39,6 +45,10 @@
             "sha512-ld+djZk8uRWmzXC+JYla1PTBScg0NjP/8x9vOOKRW+DuJ3NNMRjrpfbY7T77Jgnc87dZZsU49robbQfYe3ukug=="
           ]
         },
+        "private": {
+          "type": "boolean",
+          "description": "Was this SDK installed as a private, unpublished, package to the filesystem?"
+        },
         "source": {
           "type": "string",
           "description": "The original source that was used to generate the SDK with.",
@@ -47,6 +57,12 @@
             "./petstore.json",
             "@developers/v2.0#nysezql0wwo236"
           ]
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "The date that this SDK was last rebuilt or updated.",
+          "examples": ["2023-10-19T20:35:39.268Z"]
         }
       }
     }

diff --git a/packages/api/src/commands/index.ts b/packages/api/src/commands/index.ts
@@ -1,5 +1,7 @@
 import installCommand from './install.js';
+import listCommand from './list.js';
 
 export default {
   install: installCommand,
+  list: listCommand,
 };
diff --git a/packages/api/src/commands/list.ts b/packages/api/src/commands/list.ts
@@ -0,0 +1,42 @@
+import chalk from 'chalk';
+import { Command } from 'commander';
+
+import logger from '../logger.js';
+import Storage from '../storage.js';
+
+const cmd = new Command();
+cmd
+  .name('list')
+  .alias('ls')
+  .description('list any installed API SDKs')
+  .action(async () => {
+    // We need to preload the storage system so we can grab the lockfile.
+    Storage.setStorageDir();
+
+    const lockfile = Storage.getLockfile();
+
+    if (!lockfile.apis.length) {
+      logger('😔 You do not have any SDKs installed.');
+      return;
+    }
+
+    lockfile.apis.forEach((api, i) => {
+      if (i > 0) {
+        logger('');
+      }
+
+      logger(chalk.yellow.underline(api.identifier));
+      if (api.private) {
+        logger(`package name (${chalk.red('private')}): ${chalk.grey(`@api/${api.identifier}`)}`);
+      }
+
+      logger(`source: ${chalk.grey(api.source)}`);
+      logger(`installer version: ${chalk.grey(api.installerVersion)}`);
+      logger(`created at: ${chalk.grey(api.createdAt || 'n/a')}`);
+      if (api.updatedAt) {
+        logger(`updated at: ${chalk.grey(api.updatedAt)}`);
+      }
+    });
+  });
+
+export default cmd;
diff --git a/packages/api/src/storage.ts b/packages/api/src/storage.ts
@@ -84,7 +84,6 @@ export default class Storage {
 
     return {
       $schema: `https://unpkg.com/api@${majorVersion}/schema.json`,
-      version: '1.0',
       apis: [],
     };
   }
@@ -276,10 +275,12 @@ export default class Storage {
       }
 
       (Storage.lockfile as Lockfile).apis.push({
+        private: true,
         identifier: this.identifier,
         source: this.source,
         integrity: Storage.generateIntegrityHash(spec),
         installerVersion: PACKAGE_VERSION,
+        createdAt: new Date().toISOString(),
       } as LockfileAPI);
 
       fs.writeFileSync(path.join(identifierStorageDir, 'openapi.json'), saved);
@@ -296,24 +297,29 @@ export default class Storage {
  * @see schema.json
  */
 interface Lockfile {
+  /**
+   * @since `Lockfile.version: 2.0`
+   */
   $schema: string;
 
   /**
    * The list of installed APIs.
    */
   apis: LockfileAPI[];
-
-  /**
-   * The `api.json` schema version. This will only ever change if we introduce breaking changes to
-   * this store.
-   */
-  version: '1.0';
 }
 
 /**
  * @see schema.json
  */
 interface LockfileAPI {
+  /**
+   * The date that this SDK was installed.
+   *
+   * @since 7.0
+   * @example 2023-10-19T20:35:39.268Z
+   */
+  createdAt: string;
+
   /**
    * A unique identifier of the API. This'll be used to do imports on `@api/<identifier>` and also
    * where the SDK code will be located in `.api/apis/<identifier>`.
@@ -337,6 +343,13 @@ interface LockfileAPI {
    */
   integrity: string;
 
+  /**
+   * Was this SDK installed as a private, unpublished, package to the filesystem?
+   *
+   * @since 7.0
+   */
+  private?: boolean;
+
   /**
    * The original source that was used to generate the SDK with.
    *
@@ -345,4 +358,12 @@ interface LockfileAPI {
    * @example @developers/v2.0#nysezql0wwo236
    */
   source: string;
+
+  /**
+   * The date that this SDK was last rebuilt or updated.
+   *
+   * @since 7.0
+   * @example 2023-10-19T20:35:39.268Z
+   */
+  updatedAt?: string;
 }