stepzen 0.16.0 → 0.17.0-beta.2

package/lib/generate/curl2sdl.d.ts

@@ -1,24 +1,6 @@
 import { CurlArguments } from '../shared/curl-parser';
 import { PathParam } from '../shared/path-params-parser';
-export declare type NameValueHeaderInput = {
-    name: string;
-    value: string;
-};
-export declare type NamePartsHeaderInput = {
-    name: string;
-    parts: HeaderInputValuePart[];
-};
-export declare type HeaderInput = NameValueHeaderInput | NamePartsHeaderInput;
-export declare type HeaderInputConstantValuePart = {
-    kind: 'Constant';
-    value: string;
-};
-export declare type HeaderInputVariableValuePart = {
-    kind: 'Variable';
-    value: string;
-    name: string;
-};
-export declare type HeaderInputValuePart = HeaderInputConstantValuePart | HeaderInputVariableValuePart;
+import { HeaderInput } from '../shared/header';
 export declare type Curl2SdlOptions = {
     curlArgs: CurlArguments;
     name?: string;
@@ -28,6 +10,7 @@ export declare type Curl2SdlOptions = {
     typePrefix?: string;
     pathParams: readonly PathParam[];
     headers: readonly HeaderInput[];
+    onConflict: 'overwrite' | 'append';
 };
 export declare type EditableCurl2SdlOptions = Pick<Curl2SdlOptions, 'curlArgs' | 'queryName' | 'rootType' | 'typePrefix' | 'pathParams'>;
 export declare type CurlAnswers = {
@@ -65,7 +48,7 @@ export declare const compileParameterList: (headers: HeaderInput[], pathParams:
  */
 export declare const makeDuplicateParamsMessage: (headers: HeaderInput[], pathParams: PathParam[], url: string) => string | null;
 export declare const askCurlQuestions: (defaultAnswers?: Partial<CurlAnswers>) => Promise<EditableCurl2SdlOptions>;
-export declare const curl2sdl: ({ curlArgs, name, source, queryName, rootType, typePrefix, pathParams, headers, }: Curl2SdlOptions) => Promise<{
+export declare const curl2sdl: ({ curlArgs, name, source, queryName, rootType, typePrefix, pathParams, headers, onConflict, }: Curl2SdlOptions) => Promise<{
     error: string;
 } | {
     outPath: string;

package/lib/generate/curl2sdl.js

@@ -2,22 +2,13 @@
 // Copyright (c) 2020,2021,2022, StepZen, Inc.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.curl2sdl = exports.askCurlQuestions = exports.makeDuplicateParamsMessage = exports.compileParameterList = void 0;
-const errors_1 = require("@oclif/errors");
 const chalk = require("chalk");
-const fs = require("fs-extra");
 const inquirer = require("inquirer");
 const lodash_1 = require("lodash");
-const os = require("os");
-const path = require("path");
 const string_argv_1 = require("string-argv");
-const node_fetch_1 = require("node-fetch");
-const debug = require("debug");
-const prettier = require("prettier");
-const transpiler_1 = require("@stepzen/transpiler");
 const curl_parser_1 = require("../shared/curl-parser");
 const path_params_parser_1 = require("../shared/path-params-parser");
-const constants_1 = require("../shared/constants");
-const errors_2 = require("../shared/errors");
+const helpers_1 = require("./helpers");
 /**
  * Collect together all query parameters from HTTP headers and from the
  * pathname, and return them as a uniform list.
@@ -116,7 +107,7 @@ exports.askCurlQuestions = async (defaultAnswers = {}) => {
         },
         {
             name: 'typePrefix',
-            message: 'Prefix to add to all generated type name (leave blank to use defaults)',
+            message: 'Prefix to add to all generated type names (leave blank to use defaults)',
         },
     ];
     questions = questions.map(question => (Object.assign(Object.assign({}, question), { default: lodash_1.get(defaultAnswers, question.name) })));
@@ -151,107 +142,46 @@ exports.askCurlQuestions = async (defaultAnswers = {}) => {
         pathParams: parsedPathParamsOrError,
     };
 };
-exports.curl2sdl = async ({ curlArgs, name, source, queryName, rootType, typePrefix, pathParams, headers, }) => {
-    let json;
-    try {
-        const url = `${constants_1.STEPZEN_JSON2SDL_SERVER_URL}/api/graphql`;
-        const query = `query (
-      $command: String!
-      $queryName: String
-      $rootType: String
-      $typePrefix: String
-      $headers: [HeaderInput!]
-      $data: String
-      $method: HTTPMethod
-      $pathParams: [PathParamInput!]
-    ) {
-      getSDLFromCurl(
-        command: $command
-        queryName: $queryName
-        rootType: $rootType
-        typePrefix: $typePrefix
-        headers: $headers
-        data: $data
-        method: $method
-        pathParams: $pathParams
-      ) {
-        sdl
-        config
-      }
-    }`;
-        const variables = {
-            command: curlArgs.url,
-            queryName: queryName || null,
-            rootType: rootType || null,
-            typePrefix: typePrefix || null,
-            headers: headers.length > 0 ? headers : null,
-            data: curlArgs.data || null,
-            method: curlArgs.method,
-            pathParams: pathParams.length > 0 ? pathParams : null,
-        };
-        debug('stepzen:curl2sdl')(url);
-        debug('stepzen:curl2sdl')(query);
-        debug('stepzen:curl2sdl')(variables);
-        const payload = JSON.stringify({
-            query,
-            variables,
-        });
-        debug('stepzen:curl2sdl')(payload);
-        const response = await node_fetch_1.default(url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                query,
-                variables,
-            }),
-        });
-        const text = await response.text();
-        debug('stepzen:curl2sdl')(text);
-        json = JSON.parse(text);
-    }
-    catch (error) {
-        debug('stepzen:curl2sdl')(error);
-        throw new errors_1.CLIError(errors_2.PERMANENT_STEPZEN_ERROR);
-    }
-    if (!json.data && !json.errors) {
-        debug('stepzen:curl2sdl')('expected the response from the JSON introspection service ' +
-            'to contain either `data` or `errors`');
-        throw new errors_1.CLIError(errors_2.PERMANENT_STEPZEN_ERROR);
-    }
-    if (json.errors) {
-        return { error: json.errors.map((error) => error.message).join('\n') };
-    }
-    const { getSDLFromCurl } = json.data;
-    if (!getSDLFromCurl) {
-        debug('stepzen:curl2sdl')('expected the response from the JSON introspection service ' +
-            'to contain a `getSDLFromCurl` object');
-        throw new errors_1.CLIError(errors_2.PERMANENT_STEPZEN_ERROR);
-    }
-    const { config, sdl } = getSDLFromCurl;
-    if (!config && !sdl) {
-        debug('stepzen:curl2sdl')('expected the response from the JSON introspection service ' +
-            'to contain at least one of `getSDLFromCurl.config` or ' +
-            '`getSDLFromCurl.sdl` properties');
-        throw new errors_1.CLIError(errors_2.PERMANENT_STEPZEN_ERROR);
-    }
-    // write out the generated config and schema files
-    const tmp = path.join(os.tmpdir(), `stepzen-curl2sdl-${Date.now()}`);
-    fs.ensureDirSync(tmp);
-    // fs.ensureDirSync(path.join(tmp, subfolder))
-    if (config) {
-        fs.writeFileSync(path.join(tmp, 'config.yaml'), prettier.format(config, { parser: 'yaml' }));
-    }
-    if (sdl) {
-        fs.writeFileSync(path.join(tmp, 'index.graphql'), prettier.format(sdl, { parser: 'graphql' }));
-    }
-    const result = await transpiler_1.merge(source, {
-        name: name || 'curl',
-        source: tmp,
-    }, {
-        answers: {},
-        output: null,
-        silent: true,
-        mergeTypes: false,
+exports.curl2sdl = async ({ curlArgs, name, source, queryName, rootType, typePrefix, pathParams, headers, onConflict, }) => {
+    const response = await helpers_1.queryIntrospectionService({
+        operation: 'getSDLFromCurl',
+        variables: {
+            command: {
+                type: 'String!',
+                value: curlArgs.url,
+            },
+            queryName: {
+                type: 'String',
+                value: queryName || null,
+            },
+            rootType: {
+                type: 'String',
+                value: rootType || null,
+            },
+            typePrefix: {
+                type: 'String',
+                value: typePrefix || null,
+            },
+            headers: {
+                type: '[HeaderInput!]',
+                value: headers && headers.length > 0 ? headers : null,
+            },
+            data: {
+                type: 'String',
+                value: curlArgs.data || null,
+            },
+            method: {
+                type: 'HTTPMethod!',
+                value: curlArgs.method,
+            },
+            pathParams: {
+                type: '[PathParamInput!]',
+                value: pathParams.length > 0 ? pathParams : null,
+            },
+        },
     });
-    return { outPath: result };
+    if (response.error) {
+        return { error: response.error };
+    }
+    return helpers_1.writeSdlAndConfig(name || 'curl', source, onConflict, response);
 };

package/lib/generate/graphql2sdl.d.ts

@@ -0,0 +1,23 @@
+import { HeaderInput } from '../shared/header';
+export declare type GraphQL2SdlOptions = {
+    name?: string;
+    source: string;
+    endpoint: string;
+    typePrefix?: string;
+    includeRootOperations?: boolean;
+    header?: string;
+    onConflict: 'overwrite' | 'append';
+};
+export declare type EditableGraphQL2SdlOptions = Pick<GraphQL2SdlOptions, 'endpoint' | 'typePrefix' | 'includeRootOperations' | 'header'>;
+export declare type GraphQLAnswers = {
+    endpoint: string;
+    typePrefix: string;
+    includeRootOperations: boolean;
+    headers: readonly HeaderInput[];
+};
+export declare const askGraphQLQuestions: (defaultAnswers?: Partial<GraphQLAnswers>) => Promise<EditableGraphQL2SdlOptions>;
+export declare const graphql2sdl: ({ name, source, endpoint, typePrefix, includeRootOperations, header, onConflict, }: GraphQL2SdlOptions) => Promise<{
+    error: string;
+} | {
+    outPath: string;
+}>;

package/lib/generate/graphql2sdl.js

@@ -0,0 +1,62 @@
+"use strict";
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.graphql2sdl = exports.askGraphQLQuestions = void 0;
+const inquirer = require("inquirer");
+const lodash_1 = require("lodash");
+const header_1 = require("../shared/header");
+const helpers_1 = require("./helpers");
+exports.askGraphQLQuestions = async (defaultAnswers = {}) => {
+    let questions = [
+        {
+            name: 'endpoint',
+            message: 'What is the GraphQL endpoint URL?',
+            validate: input => input.trim() !== '',
+        },
+        {
+            name: 'typePrefix',
+            message: 'Prefix to add to all generated type names (leave blank for none)',
+        },
+        {
+            name: 'includeRootOperations',
+            type: 'confirm',
+            message: 'Should type prefix be added to query and mutation fields as well?',
+            when: answers => Boolean(answers.typePrefix),
+        },
+        {
+            name: 'header',
+            type: 'input',
+            message: 'Add an HTTP header, e.g. Header-Name: header value (leave blank for none)',
+            validate: input => input === '' || header_1.HEADER_REGEX.test(input.trim()) || 'invalid header',
+        },
+    ];
+    questions = questions.map(question => (Object.assign(Object.assign({}, question), { default: lodash_1.get(defaultAnswers, question.name) })));
+    return inquirer.prompt(questions);
+};
+exports.graphql2sdl = async ({ name, source, endpoint, typePrefix, includeRootOperations, header, onConflict, }) => {
+    const response = await helpers_1.queryIntrospectionService({
+        operation: 'getSDLFromGraphQL',
+        variables: {
+            endpoint: {
+                type: 'String!',
+                value: endpoint,
+            },
+            typePrefix: {
+                type: 'String',
+                value: typePrefix || null,
+            },
+            includeRootOperations: {
+                type: 'Boolean',
+                value: includeRootOperations || null,
+            },
+            headers: {
+                type: '[HeaderInput!]',
+                value: header ? [header_1.parseHeaderNameValue(header)] : null,
+            },
+        },
+    });
+    if (response.error) {
+        return { error: response.error };
+    }
+    return helpers_1.writeSdlAndConfig(name || 'graphql', source, onConflict, response);
+};

package/lib/generate/helpers.d.ts

@@ -11,4 +11,21 @@ export declare const getSchema: (arg: string) => string;
 export declare const getTemplates: () => Promise<string>;
 export declare const askGeneratorQuestions: (id: string, settings: any, state: any) => Promise<any>;
 export declare const askTemplateQuestions: (id: string, settings: any, state: any) => Promise<any>;
-export declare const mergeFiles: (name: string, source: string, files: string, answers: any) => Promise<string>;
+export declare type IntrospectionServiceQuery = {
+    operation: string;
+    variables: {
+        [id: string]: {
+            type: string;
+            value: any | null;
+        };
+    };
+};
+export declare type IntrospectionServiceResponse = {
+    sdl?: string;
+    config?: string;
+    error?: string;
+};
+export declare const queryIntrospectionService: (query: IntrospectionServiceQuery) => Promise<IntrospectionServiceResponse>;
+export declare const writeSdlAndConfig: (name: string, source: string, onConflict: 'overwrite' | 'append', { config, sdl }: IntrospectionServiceResponse) => Promise<{
+    outPath: string;
+}>;

package/lib/generate/helpers.js

@@ -1,7 +1,7 @@
 "use strict";
 // Copyright (c) 2020,2021,2022, StepZen, Inc.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mergeFiles = exports.askTemplateQuestions = exports.askGeneratorQuestions = exports.getTemplates = exports.getSchema = exports.getConfiguration = exports.createGeneratorFiles = void 0;
+exports.writeSdlAndConfig = exports.queryIntrospectionService = exports.askTemplateQuestions = exports.askGeneratorQuestions = exports.getTemplates = exports.getSchema = exports.getConfiguration = exports.createGeneratorFiles = void 0;
 const errors_1 = require("@oclif/errors");
 const chalk = require("chalk");
 const debug = require("debug");
@@ -13,6 +13,7 @@ const os = require("os");
 const path = require("path");
 const shell = require("shelljs");
 const transpiler = require("@stepzen/transpiler");
+const prettier = require("prettier");
 const constants_1 = require("../shared/constants");
 const errors_2 = require("../shared/errors");
 const { version } = require('../../package.json');
@@ -93,7 +94,7 @@ exports.getSchema = (arg) => {
     const schema = arg.trim();
     // Now supports importing only one schema at a time:
     // https://github.com/steprz/stepzen-cli/issues/628
-    if (schema.includes(',')) {
+    if (schema.includes(',') || schema.includes(' ')) {
         throw new errors_1.CLIError("Importing multiple schemas is no longer supported; please specify only one (e.g. 'stepzen import mysql')");
     }
     // support `postgres` as an alias to `postgresql`
@@ -160,14 +161,86 @@ exports.askTemplateQuestions = async (id, settings, state) => {
     const answers = await inquirer.prompt(questions);
     return Object.assign(Object.assign({}, state), answers);
 };
-exports.mergeFiles = async (name, source, files, answers) => {
-    const output = await transpiler.merge(source, {
+exports.queryIntrospectionService = async (query) => {
+    let json;
+    try {
+        const url = `${constants_1.STEPZEN_JSON2SDL_SERVER_URL}/api/graphql`;
+        debug('stepzen:introspection')(url);
+        const queryString = `query (
+      ${Object.entries(query.variables).map(([id, { type }]) => `$${id}: ${type}`)} 
+      ) { 
+        ${query.operation}(${Object.keys(query.variables).map(id => `${id}: $${id}`)}) {
+          sdl
+          config
+        } 
+    }`;
+        debug('stepzen:introspection')(queryString);
+        debug('stepzen:introspection')(query.variables);
+        const payload = JSON.stringify({
+            query: queryString,
+            variables: lodash_1.mapValues(query.variables, ({ value }) => value),
+        });
+        debug('stepzen:introspection')(payload);
+        const response = await node_fetch_1.default(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: payload,
+        });
+        const text = await response.text();
+        debug('stepzen:introspection')(text);
+        json = JSON.parse(text);
+    }
+    catch (error) {
+        debug('stepzen:introspection')(error);
+        throw new errors_1.CLIError(errors_2.PERMANENT_STEPZEN_ERROR);
+    }
+    if (!json.data && !json.errors) {
+        debug('stepzen:introspection')('expected the response from the JSON introspection service ' +
+            'to contain either `data` or `errors`');
+        throw new errors_1.CLIError(errors_2.PERMANENT_STEPZEN_ERROR);
+    }
+    if (json.errors) {
+        const compileError = (error) => {
+            var _a;
+            return error.message +
+                (((_a = error.extensions) === null || _a === void 0 ? void 0 : _a.details) ? `: ${error.extensions.details}` : '');
+        };
+        return { error: json.errors.map(compileError).join('\n') };
+    }
+    if (!json.data[query.operation]) {
+        debug('stepzen:graphql2sdl')('expected the response from the JSON introspection service ' +
+            `to contain a \`${query.operation}\` object`);
+        throw new errors_1.CLIError(errors_2.PERMANENT_STEPZEN_ERROR);
+    }
+    const { config, sdl } = json.data[query.operation];
+    if (!config && !sdl) {
+        debug('stepzen:curl2sdl')('expected the response from the JSON introspection service ' +
+            `to contain at least one of \`${query.operation}.config\` or ` +
+            `\`${query.operation}.sdl\` properties`);
+        throw new errors_1.CLIError(errors_2.PERMANENT_STEPZEN_ERROR);
+    }
+    return { config, sdl };
+};
+exports.writeSdlAndConfig = async (name, source, onConflict, { config, sdl }) => {
+    // write out the generated config and schema files
+    const tmp = path.join(os.tmpdir(), `stepzen-introspection-${Date.now()}`);
+    fs.ensureDirSync(tmp);
+    // fs.ensureDirSync(path.join(tmp, subfolder))
+    if (config) {
+        fs.writeFileSync(path.join(tmp, 'config.yaml'), prettier.format(config, { parser: 'yaml' }));
+    }
+    if (sdl) {
+        fs.writeFileSync(path.join(tmp, 'index.graphql'), prettier.format(sdl, { parser: 'graphql' }));
+    }
+    const result = await transpiler.merge(source, {
         name: name,
-        source: files,
+        source: tmp,
     }, {
-        answers,
-        silent: true,
+        answers: {},
         output: null,
+        silent: true,
+        mergeTypes: false,
+        onConflict,
     });
-    return output;
+    return { outPath: result };
 };

package/lib/generate/index.d.ts

@@ -1,4 +1,11 @@
-declare const _default: (schema: string, name: string | undefined, source: string, preAnswered?: {
-    [question: string]: string;
-}) => Promise<string>;
+export declare type GenerateOptions = {
+    schema: string;
+    name?: string;
+    onConflict: 'overwrite' | 'append';
+    source: string;
+    preAnswered?: {
+        [question: string]: string;
+    };
+};
+declare const _default: ({ schema, name, onConflict, source, preAnswered, }: GenerateOptions) => Promise<string>;
 export default _default;

package/lib/generate/index.js

@@ -6,8 +6,9 @@ const core_1 = require("@oclif/core");
 const fs = require("fs-extra");
 const lodash = require("lodash");
 const path = require("path");
+const transpiler = require("@stepzen/transpiler");
 const helpers_1 = require("./helpers");
-exports.default = async (schema, name, source, preAnswered = {}) => {
+exports.default = async ({ schema, name, onConflict, source, preAnswered = {}, }) => {
     var _a, _b;
     // Store the generator
     let generator;
@@ -82,7 +83,15 @@ exports.default = async (schema, name, source, preAnswered = {}) => {
         // if (generator.type === 'template')
         files = path.join(templates, schema);
     }
-    const output = await helpers_1.mergeFiles(name || schema, source, files, answers);
+    const output = await transpiler.merge(source, {
+        name: name || schema,
+        source: files,
+    }, {
+        answers,
+        silent: true,
+        output: null,
+        onConflict,
+    });
     core_1.CliUx.ux.action.stop();
     // Housekeeping
     cleanUp();

package/lib/shared/header-params-parser.d.ts

@@ -1,4 +1,4 @@
-import { HeaderInput } from '../generate/curl2sdl';
+import { HeaderInput } from './header';
 import { ParseError, CurlHeader } from './curl-parser';
 export declare const parseHeaderParam: (headers: readonly CurlHeader[], headerParam: string) => {
     header: HeaderInput;

package/lib/shared/header.d.ts

@@ -0,0 +1,21 @@
+export declare type NameValueHeaderInput = {
+    name: string;
+    value: string;
+};
+export declare type NamePartsHeaderInput = {
+    name: string;
+    parts: HeaderInputValuePart[];
+};
+export declare type HeaderInput = NameValueHeaderInput | NamePartsHeaderInput;
+export declare type HeaderInputConstantValuePart = {
+    kind: 'Constant';
+    value: string;
+};
+export declare type HeaderInputVariableValuePart = {
+    kind: 'Variable';
+    value: string;
+    name: string;
+};
+export declare type HeaderInputValuePart = HeaderInputConstantValuePart | HeaderInputVariableValuePart;
+export declare const HEADER_REGEX: RegExp;
+export declare const parseHeaderNameValue: (input: string) => NameValueHeaderInput | null;

package/lib/shared/header.js

@@ -0,0 +1,13 @@
+"use strict";
+// Copyright (c) 2020,2021,2022, StepZen, Inc.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseHeaderNameValue = exports.HEADER_REGEX = void 0;
+exports.HEADER_REGEX = /([\w-]+): (.*)/;
+exports.parseHeaderNameValue = (input) => {
+    const match = input.match(exports.HEADER_REGEX);
+    if (match) {
+        const [name, value] = match.splice(1, 2);
+        return { name, value };
+    }
+    return null;
+};

package/lib/shared/utils.d.ts

@@ -1,5 +1,19 @@
-export declare const clearConsole: () => void;
 export declare const getDirectory: (d?: string | undefined) => string;
+/**
+ * Replace the path prefix with `~` if it is inside the user's home directory.
+ *
+ * @param {*} absPath an absolute file or directory path
+ * @returns {*} the same path that possibly looks more friendly to users
+ */
+export declare const homeRelative: (absPath: string) => string;
+/**
+ * Replace the path prefix with `~` if it is inside the user's home directory.
+ *
+ * @param {*} absPath an absolute file or directory path
+ * @param {*} workspace an absolute file or the workspace root
+ * @returns {*} the same path that possibly looks more friendly to users
+ */
+export declare const workspaceRelative: (absPath: string, workspace: string) => string;
 export declare const getStepZenExtensions: () => Promise<string>;
 export declare const validateEndpoint: (endpoint: string) => any;
 export declare const maskStepZenKey: (key: string) => string;

package/lib/shared/utils.js

@@ -1,7 +1,7 @@
 "use strict";
 // Copyright (c) 2020,2021,2022, StepZen, Inc.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.maskStepZenKey = exports.validateEndpoint = exports.getStepZenExtensions = exports.getDirectory = exports.clearConsole = void 0;
+exports.maskStepZenKey = exports.validateEndpoint = exports.getStepZenExtensions = exports.workspaceRelative = exports.homeRelative = exports.getDirectory = void 0;
 const errors_1 = require("@oclif/errors");
 const debug = require("debug");
 const node_fetch_1 = require("node-fetch");
@@ -10,12 +10,6 @@ const os = require("os");
 const path = require("path");
 const prettier = require("prettier");
 const constants_1 = require("./constants");
-exports.clearConsole = () => {
-    process.stdout.write(
-    // Taken from create-react-app
-    // eslint-disable-next-line unicorn/no-hex-escape
-    process.platform === 'win32' ? '\x1B[2J\x1B[0f' : '\x1B[2J\x1B[3J\x1B[H');
-};
 exports.getDirectory = (d = process.cwd()) => {
     let directory = d;
     // If it starts with `~`, expand this
@@ -31,6 +25,33 @@ exports.getDirectory = (d = process.cwd()) => {
     }
     return directory;
 };
+/**
+ * Replace the path prefix with `~` if it is inside the user's home directory.
+ *
+ * @param {*} absPath an absolute file or directory path
+ * @returns {*} the same path that possibly looks more friendly to users
+ */
+exports.homeRelative = (absPath) => {
+    let pretty = absPath;
+    if (absPath.startsWith(os.homedir())) {
+        pretty = '~' + absPath.substring(os.homedir().length);
+    }
+    return pretty;
+};
+/**
+ * Replace the path prefix with `~` if it is inside the user's home directory.
+ *
+ * @param {*} absPath an absolute file or directory path
+ * @param {*} workspace an absolute file or the workspace root
+ * @returns {*} the same path that possibly looks more friendly to users
+ */
+exports.workspaceRelative = (absPath, workspace) => {
+    let pretty = absPath;
+    if (absPath.startsWith(workspace)) {
+        pretty = '.' + absPath.substring(workspace.length);
+    }
+    return pretty;
+};
 exports.getStepZenExtensions = async () => {
     const domain = constants_1.STEPZEN_DOMAIN.replace('.io', '.net');
     const url = `https://www.${domain}/directives.graphql`;

package/lib/shared/workspace.d.ts

@@ -1,2 +1,10 @@
 import { Workspace } from './types';
+export declare const validateWorkspaceName: (directory: string, name: string) => boolean;
+export declare const generateWorkspaceName: (directory: string) => string;
+export declare const guessSchemaRoot: (directory: string) => string;
 export declare const getWorkspace: (directory: string) => Workspace | null;
+export declare const initWorkspace: (args: {
+    directory?: string;
+    endpoint?: string;
+    yes?: boolean;
+}) => Promise<Workspace>;